@epsilon-asi/foundation 0.0.10 → 0.0.12

package/build/files/layered.js

@@ -0,0 +1,133 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverLayers = discoverLayers;
+exports.discoverLayersSync = discoverLayersSync;
+exports.loadMergedFiles = loadMergedFiles;
+exports.loadMergedFilesSync = loadMergedFilesSync;
+exports.loadLayeredFile = loadLayeredFile;
+exports.loadLayeredFileSync = loadLayeredFileSync;
+exports.safeLoadLayeredFile = safeLoadLayeredFile;
+exports.safeLoadLayeredFileSync = safeLoadLayeredFileSync;
+exports.createLayeredFile = createLayeredFile;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const types_1 = require("./types");
+const util_1 = require("./util");
+/**
+ * Every place `fileName` may live, highest precedence first: the start directory, each ancestor up to
+ * `stopDir` (or the root), then the fallbacks. Duplicates keep their highest-precedence slot.
+ */
+function candidates(fileName, options) {
+    var _a, _b;
+    const start = node_path_1.default.resolve((0, util_1.expandHome)((_a = options.startDir) !== null && _a !== void 0 ? _a : process.cwd()));
+    const stopAt = options.stopDir === undefined ? undefined : node_path_1.default.resolve((0, util_1.expandHome)(options.stopDir));
+    const all = [];
+    for (let dir = start;; dir = node_path_1.default.dirname(dir)) {
+        all.push({ filePath: node_path_1.default.join(dir, fileName), origin: dir === start ? "local" : "ancestor" });
+        if (dir === stopAt || dir === node_path_1.default.dirname(dir))
+            break;
+    }
+    for (const fallback of (_b = options.fallbacks) !== null && _b !== void 0 ? _b : []) {
+        all.push({ filePath: node_path_1.default.resolve((0, util_1.expandHome)(fallback)), origin: "fallback" });
+    }
+    const seen = new Set();
+    return all.filter(({ filePath }) => !seen.has(filePath) && Boolean(seen.add(filePath)));
+}
+/**
+ * Find every existing `fileName` (a name or a relative path such as `.tool/config.yaml`) from
+ * `startDir` upwards, then among `fallbacks`. Results are ordered highest precedence first.
+ */
+function discoverLayers(fileName_1) {
+    return __awaiter(this, arguments, void 0, function* (fileName, options = {}) {
+        const all = candidates(fileName, options);
+        const present = yield Promise.all(all.map(({ filePath }) => (0, util_1.pathExists)(filePath)));
+        return all.filter((_, i) => present[i]);
+    });
+}
+function discoverLayersSync(fileName, options = {}) {
+    return candidates(fileName, options).filter(({ filePath }) => (0, node_fs_1.existsSync)(filePath));
+}
+/** A layer must be a mapping to merge; an empty file contributes nothing. */
+function asLayer(raw, filePath) {
+    if (raw === undefined || (0, util_1.isPlainObject)(raw))
+        return raw;
+    throw new types_1.SchemaFileError("validate", `Cannot merge ${filePath}: its top level must be a mapping`, { filePath });
+}
+/** Validation runs on the merged value, so errors name every file that went into it. */
+function mergedOptions(filePaths, options) {
+    const filePath = filePaths.length > 1 ? `merged ${filePaths.join(", ")}` : filePaths[0];
+    return Object.assign(Object.assign({}, options), { filePath });
+}
+/**
+ * Load several JSON/YAML files, deep-merge them and validate the result once.
+ * `filePaths` is highest precedence first. Each file is read raw (no schema defaults), so a
+ * lower layer's value is never masked by a default; defaults apply only to keys no layer sets.
+ */
+function loadMergedFiles(filePaths_1, schema_1) {
+    return __awaiter(this, arguments, void 0, function* (filePaths, schema, options = {}) {
+        const layers = yield Promise.all(filePaths.map((filePath) => __awaiter(this, void 0, void 0, function* () { return asLayer(yield (0, util_1.readRawAsync)(filePath, options), filePath); })));
+        return (0, util_1.validateAsync)(schema, (0, util_1.deepMerge)(...layers.reverse()), mergedOptions(filePaths, options));
+    });
+}
+function loadMergedFilesSync(filePaths, schema, options = {}) {
+    const layers = filePaths.map((filePath) => asLayer((0, util_1.readRawSync)(filePath, options), filePath));
+    return (0, util_1.validateSync)(schema, (0, util_1.deepMerge)(...layers.reverse()), mergedOptions(filePaths, options));
+}
+/**
+ * Discover every `fileName` layer (see discoverLayers), merge them and validate.
+ * Precedence: start directory > nearer ancestors > farther ancestors > fallbacks, in order.
+ * With no layers found, the schema validates `{}`, so its defaults apply.
+ */
+function loadLayeredFile(fileName_1, schema_1) {
+    return __awaiter(this, arguments, void 0, function* (fileName, schema, options = {}) {
+        const layers = yield discoverLayers(fileName, options);
+        const value = yield loadMergedFiles(layers.map((layer) => layer.filePath), schema, options);
+        return { value, layers };
+    });
+}
+/** Synchronous variant. Fails if the schema contains async refinements/transforms. */
+function loadLayeredFileSync(fileName, schema, options = {}) {
+    const layers = discoverLayersSync(fileName, options);
+    const value = loadMergedFilesSync(layers.map((layer) => layer.filePath), schema, options);
+    return { value, layers };
+}
+/** Like loadLayeredFile, but returns a result object instead of throwing SchemaFileError. */
+function safeLoadLayeredFile(fileName, schema, options = {}) {
+    return (0, util_1.safely)(() => loadLayeredFile(fileName, schema, options));
+}
+function safeLoadLayeredFileSync(fileName, schema, options = {}) {
+    return (0, util_1.safelySync)(() => loadLayeredFileSync(fileName, schema, options));
+}
+/**
+ * Bind a schema, file name and default options once, reuse everywhere.
+ * Per-call options are shallow-merged over the defaults, e.g. `config.load({startDir})`.
+ *
+ * @example
+ * const Config = createLayeredFile(ConfigSchema, "tool.yaml", {fallbacks: ["~/.tool/tool.yaml"]});
+ * const {value, layers} = await Config.load();
+ */
+function createLayeredFile(schema, fileName, defaults = {}) {
+    const o = (options) => (Object.assign(Object.assign({}, defaults), options));
+    return {
+        schema,
+        fileName,
+        discover: (options) => discoverLayers(fileName, o(options)),
+        discoverSync: (options) => discoverLayersSync(fileName, o(options)),
+        load: (options) => loadLayeredFile(fileName, schema, o(options)),
+        loadSync: (options) => loadLayeredFileSync(fileName, schema, o(options)),
+        safeLoad: (options) => safeLoadLayeredFile(fileName, schema, o(options)),
+        safeLoadSync: (options) => safeLoadLayeredFileSync(fileName, schema, o(options)),
+    };
+}

package/build/files/load.d.ts

@@ -0,0 +1,9 @@
+import * as z from "zod";
+import { LoadOptions, SafeResult } from "./types";
+/** Read a JSON/YAML file and return a validated, typed value. */
+export declare function loadFile<S extends z.ZodType>(filePath: string, schema: S, options?: LoadOptions): Promise<z.output<S>>;
+/** Synchronous variant. Fails if the schema contains async refinements/transforms. */
+export declare function loadFileSync<S extends z.ZodType>(filePath: string, schema: S, options?: LoadOptions): z.output<S>;
+/** Like loadFile, but returns a result object instead of throwing SchemaFileError. */
+export declare function safeLoadFile<S extends z.ZodType>(filePath: string, schema: S, options?: LoadOptions): Promise<SafeResult<z.output<S>>>;
+export declare function safeLoadFileSync<S extends z.ZodType>(filePath: string, schema: S, options?: LoadOptions): SafeResult<z.output<S>>;

package/build/files/load.js

@@ -0,0 +1,33 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadFile = loadFile;
+exports.loadFileSync = loadFileSync;
+exports.safeLoadFile = safeLoadFile;
+exports.safeLoadFileSync = safeLoadFileSync;
+const util_1 = require("./util");
+/** Read a JSON/YAML file and return a validated, typed value. */
+function loadFile(filePath_1, schema_1) {
+    return __awaiter(this, arguments, void 0, function* (filePath, schema, options = {}) {
+        return (0, util_1.validateAsync)(schema, yield (0, util_1.readRawAsync)(filePath, options), Object.assign(Object.assign({}, options), { filePath }));
+    });
+}
+/** Synchronous variant. Fails if the schema contains async refinements/transforms. */
+function loadFileSync(filePath, schema, options = {}) {
+    return (0, util_1.validateSync)(schema, (0, util_1.readRawSync)(filePath, options), Object.assign(Object.assign({}, options), { filePath }));
+}
+/** Like loadFile, but returns a result object instead of throwing SchemaFileError. */
+function safeLoadFile(filePath, schema, options = {}) {
+    return (0, util_1.safely)(() => loadFile(filePath, schema, options));
+}
+function safeLoadFileSync(filePath, schema, options = {}) {
+    return (0, util_1.safelySync)(() => loadFileSync(filePath, schema, options));
+}

package/build/files/parse.d.ts

@@ -0,0 +1,5 @@
+import * as z from "zod";
+import { ParseOptions } from "./types";
+/** Parse and validate a string already in memory. */
+export declare function parseString<S extends z.ZodType>(schema: S, text: string, options?: ParseOptions): Promise<z.output<S>>;
+export declare function parseStringSync<S extends z.ZodType>(schema: S, text: string, options?: ParseOptions): z.output<S>;

package/build/files/parse.js

@@ -0,0 +1,27 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseString = parseString;
+exports.parseStringSync = parseStringSync;
+const util_1 = require("./util");
+/** Parse and validate a string already in memory. */
+function parseString(schema_1, text_1) {
+    return __awaiter(this, arguments, void 0, function* (schema, text, options = {}) {
+        const format = (0, util_1.resolveFormat)(options.format, options.filePath, text);
+        const raw = yield (0, util_1.runPreprocess)((0, util_1.decodeText)(text, format, options), format, options);
+        return (0, util_1.validateAsync)(schema, raw, options);
+    });
+}
+function parseStringSync(schema, text, options = {}) {
+    const format = (0, util_1.resolveFormat)(options.format, options.filePath, text);
+    const raw = (0, util_1.runPreprocessSync)((0, util_1.decodeText)(text, format, options), format, options);
+    return (0, util_1.validateSync)(schema, raw, options);
+}

package/build/files/save.d.ts

@@ -0,0 +1,5 @@
+import * as z from "zod";
+import { SaveOptions } from "./types";
+export declare function saveFileSync<S extends z.ZodType>(filePath: string, schema: S, value: z.output<S>, options?: SaveOptions): string;
+/** Serialize and write to disk. Returns the text that was written. */
+export declare function saveFile<S extends z.ZodType>(filePath: string, schema: S, value: z.output<S>, options?: SaveOptions): Promise<string>;

package/build/files/save.js

@@ -0,0 +1,30 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveFileSync = saveFileSync;
+exports.saveFile = saveFile;
+const serialize_1 = require("./serialize");
+const util_1 = require("./util");
+function saveFileSync(filePath, schema, value, options = {}) {
+    const format = (0, util_1.resolveFormat)(options.format, filePath);
+    const text = (0, serialize_1.serialize)(schema, value, Object.assign(Object.assign({}, options), { format, filePath }));
+    (0, util_1.writeTextSync)(filePath, text, options);
+    return text;
+}
+/** Serialize and write to disk. Returns the text that was written. */
+function saveFile(filePath_1, schema_1, value_1) {
+    return __awaiter(this, arguments, void 0, function* (filePath, schema, value, options = {}) {
+        const format = (0, util_1.resolveFormat)(options.format, filePath);
+        const text = yield (0, serialize_1.serializeAsync)(schema, value, Object.assign(Object.assign({}, options), { format, filePath }));
+        yield (0, util_1.writeTextAsync)(filePath, text, options);
+        return text;
+    });
+}

package/build/files/serialize.d.ts

@@ -0,0 +1,6 @@
+import * as z from "zod";
+import { SerializeOptions } from "./types";
+/** Validate/encode a value with the schema and render it as JSON or YAML text. */
+export declare function serialize<S extends z.ZodType>(schema: S, value: z.output<S>, options: SerializeOptions): string;
+/** Async variant; required when the schema has async refinements or codecs. */
+export declare function serializeAsync<S extends z.ZodType>(schema: S, value: z.output<S>, options: SerializeOptions): Promise<string>;

package/build/files/serialize.js

@@ -0,0 +1,24 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serialize = serialize;
+exports.serializeAsync = serializeAsync;
+const util_1 = require("./util");
+/** Validate/encode a value with the schema and render it as JSON or YAML text. */
+function serialize(schema, value, options) {
+    return (0, util_1.render)((0, util_1.toWireSync)(schema, value, options), options);
+}
+/** Async variant; required when the schema has async refinements or codecs. */
+function serializeAsync(schema, value, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return (0, util_1.render)(yield (0, util_1.toWireAsync)(schema, value, options), options);
+    });
+}

package/build/files/types.d.ts

@@ -0,0 +1,133 @@
+import * as z from "zod";
+import * as YAML from "yaml";
+export type FileFormat = "json" | "yaml";
+export type ParseParams = Parameters<z.ZodType["safeParse"]>[1];
+export type ErrorFormatter = (error: z.core.$ZodError) => string;
+export type SchemaFileErrorKind = "format" | "read" | "parse" | "preprocess" | "validate" | "encode" | "serialize" | "write";
+export declare class SchemaFileError extends Error {
+    readonly kind: SchemaFileErrorKind;
+    readonly filePath?: string;
+    /** Present for "validate" / "encode" errors that came from Zod. */
+    readonly issues?: z.core.$ZodIssue[];
+    constructor(kind: SchemaFileErrorKind, message: string, details?: {
+        filePath?: string;
+        issues?: z.core.$ZodIssue[];
+        cause?: unknown;
+    });
+}
+export type SafeResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: SchemaFileError;
+};
+export interface PreprocessContext {
+    format: FileFormat;
+    filePath?: string;
+}
+export interface ParseOptions {
+    /** Force a format. "auto" (default) uses the file extension, then sniffs content. */
+    format?: FileFormat | "auto";
+    /** Only used for error messages and extension-based format detection. */
+    filePath?: string;
+    /** Strip a leading UTF-8 BOM. Default: true. */
+    stripBom?: boolean;
+    /** Value handed to the schema when the content is empty/whitespace. Default: undefined. */
+    emptyValue?: unknown;
+    /** Hook to transform raw parsed data before validation (env interpolation, migrations, ...). */
+    preprocess?: (raw: unknown, ctx: PreprocessContext) => unknown | Promise<unknown>;
+    /** Extra params forwarded to schema.safeParse (e.g. custom error map). */
+    parseParams?: ParseParams;
+    /** Customize the human-readable validation message. Default: z.prettifyError. */
+    formatError?: ErrorFormatter;
+    json?: {
+        reviver?: (this: unknown, key: string, value: unknown) => unknown;
+    };
+    /** Passed straight to YAML.parse (uniqueKeys, maxAliasCount, merge, version, strict, ...). */
+    yaml?: YAML.ParseOptions & YAML.DocumentOptions & YAML.SchemaOptions & YAML.ToJSOptions;
+}
+export interface LoadOptions extends ParseOptions {
+    encoding?: BufferEncoding;
+    /** If the file does not exist, validate `missingValue` instead of throwing. Default: false. */
+    allowMissing?: boolean;
+    /** Input used when the file is missing and allowMissing is true. Default: {} (so schema defaults apply). */
+    missingValue?: unknown;
+}
+/**
+ * How the in-memory (output-typed) value is turned back into plain data:
+ *  - "encode": z.encode(schema, value). Runs codecs in reverse (e.g. Date -> ISO string)
+ *              and validates. Throws on one-way .transform(). Default.
+ *  - "parse":  schema.parse(value). Validates and writes the *output* shape. Use for schemas
+ *              with one-way transforms whose output is still valid input.
+ *  - "none":   write the value as-is with no validation.
+ */
+export type SerializeStrategy = "encode" | "parse" | "none";
+export interface SerializeOptions {
+    format: FileFormat;
+    strategy?: SerializeStrategy;
+    /** Spaces of indentation. Default: 2. */
+    indent?: number;
+    /** Deterministic output: sort object keys recursively (true = default string order). */
+    sortKeys?: boolean | ((a: string, b: string) => number);
+    /** Ensure output ends with a newline. Default: true. */
+    trailingNewline?: boolean;
+    /** Customize the human-readable validation message. Default: z.prettifyError. */
+    formatError?: ErrorFormatter;
+    /** Only used for error messages. */
+    filePath?: string;
+    json?: {
+        replacer?: (this: unknown, key: string, value: unknown) => unknown;
+    };
+    yaml?: {
+        /** Options for new YAML.Document(...) (version, schema, aliasDuplicateObjects, keepUndefined, ...). */
+        document?: YAML.DocumentOptions & YAML.SchemaOptions & YAML.CreateNodeOptions;
+        /**
+         * Options for doc.toString(...) (lineWidth, defaultStringType, flowCollectionPadding, ...).
+         * Not named `toString`: every object literal inherits that, so TypeScript would reject any
+         * `yaml` options that leave it out.
+         */
+        stringify?: YAML.ToStringOptions;
+        /** Header comment written at the top of the file (multi-line allowed, no leading "#"). */
+        comment?: string;
+    };
+}
+export interface SaveOptions extends Omit<SerializeOptions, "format" | "filePath"> {
+    /** "auto" (default) picks by extension: .json / .yaml / .yml. */
+    format?: FileFormat | "auto";
+    encoding?: BufferEncoding;
+    /** Create parent directories. Default: true. */
+    createDirs?: boolean;
+    /** Write to a temp file then rename, so readers never see a half-written file. Default: true. */
+    atomic?: boolean;
+    /** Allow replacing an existing file. Default: true. */
+    overwrite?: boolean;
+    /** File permission bits for the written file, e.g. 0o600 for secrets. */
+    mode?: number;
+}
+/** Where a layer was found: the start directory, one of its ancestors, or a fallback path. */
+export type LayerOrigin = "local" | "ancestor" | "fallback";
+/** One file discovered by discoverLayers(). */
+export interface FileLayer {
+    /** Absolute path of the file. */
+    filePath: string;
+    origin: LayerOrigin;
+}
+export interface DiscoverOptions {
+    /** Directory the upward walk starts from. Default: process.cwd(). */
+    startDir?: string;
+    /** Last directory the walk visits (inclusive). Default: the filesystem root. */
+    stopDir?: string;
+    /** Paths checked after the walk, in order; they rank below every directory match. `~/` is expanded. */
+    fallbacks?: readonly string[];
+}
+/** Options for loadLayeredFile(): discovery, plus load options applied to every layer. */
+export interface LayeredLoadOptions extends Omit<LoadOptions, "filePath">, DiscoverOptions {
+}
+export interface LayeredResult<T> {
+    /** The merged, validated value. */
+    value: T;
+    /** The layers that were merged, highest precedence first. */
+    layers: FileLayer[];
+}
+export declare const EXTENSIONS: Record<string, FileFormat>;

package/build/files/types.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXTENSIONS = exports.SchemaFileError = void 0;
+class SchemaFileError extends Error {
+    constructor(kind, message, details = {}) {
+        super(message, { cause: details.cause });
+        this.name = "SchemaFileError";
+        this.kind = kind;
+        this.filePath = details.filePath;
+        this.issues = details.issues;
+    }
+}
+exports.SchemaFileError = SchemaFileError;
+exports.EXTENSIONS = {
+    ".json": "json",
+    ".yaml": "yaml",
+    ".yml": "yaml",
+};

package/build/files/util.d.ts

@@ -0,0 +1,42 @@
+import * as z from "zod";
+import { FileFormat, LoadOptions, ParseOptions, SafeResult, SaveOptions, SerializeOptions } from "./types";
+declare const MISSING: unique symbol;
+export declare function label(filePath?: string): string;
+export declare function isPlainObject(v: unknown): v is Record<string, unknown>;
+/**
+ * Recursively merge plain objects; later sources win. `undefined` values and non-object sources are
+ * skipped, arrays and scalars are replaced (not concatenated), and no source is mutated.
+ */
+export declare function deepMerge<T extends Record<string, unknown> = Record<string, unknown>>(...sources: readonly unknown[]): T;
+/** Replace a leading `~` with the current user's home directory. */
+export declare function expandHome(filePath: string): string;
+export declare function pathExists(filePath: string): Promise<boolean>;
+/** Run `run`, turning a thrown SchemaFileError into a failed SafeResult. Other errors propagate. */
+export declare function safely<T>(run: () => Promise<T>): Promise<SafeResult<T>>;
+export declare function safelySync<T>(run: () => T): SafeResult<T>;
+export declare function decodeText(text: string, format: FileFormat, opts: ParseOptions): unknown;
+export declare function formatFromExtension(filePath: string): FileFormat | undefined;
+/**
+ * Resolve a format from an explicit option, the extension, or (last) the content.
+ * Content sniffing falls back to YAML because YAML 1.2 is a superset of JSON.
+ */
+export declare function resolveFormat(format: FileFormat | "auto" | undefined, filePath?: string, content?: string): FileFormat;
+export declare function toRaw(text: string | typeof MISSING, opts: LoadOptions): {
+    raw: unknown;
+    format: FileFormat;
+};
+export declare function readTextAsync(filePath: string, opts: LoadOptions): Promise<string | typeof MISSING>;
+export declare function readTextSync(filePath: string, opts: LoadOptions): string | typeof MISSING;
+/** Read, decode and preprocess a file: everything loadFile does short of validation. */
+export declare function readRawAsync(filePath: string, options: LoadOptions): Promise<unknown>;
+export declare function readRawSync(filePath: string, options: LoadOptions): unknown;
+export declare function runPreprocess(raw: unknown, format: FileFormat, opts: ParseOptions): Promise<unknown>;
+export declare function runPreprocessSync(raw: unknown, format: FileFormat, opts: ParseOptions): unknown;
+export declare function validateAsync<S extends z.ZodType>(schema: S, raw: unknown, opts: ParseOptions): Promise<z.output<S>>;
+export declare function validateSync<S extends z.ZodType>(schema: S, raw: unknown, opts: ParseOptions): z.output<S>;
+export declare function toWireSync<S extends z.ZodType>(schema: S, value: z.output<S>, opts: SerializeOptions): unknown;
+export declare function toWireAsync<S extends z.ZodType>(schema: S, value: z.output<S>, opts: SerializeOptions): Promise<unknown>;
+export declare function render(data: unknown, opts: SerializeOptions): string;
+export declare function writeTextAsync(filePath: string, text: string, opts: SaveOptions): Promise<void>;
+export declare function writeTextSync(filePath: string, text: string, opts: SaveOptions): void;
+export {};