@epsilon-asi/foundation 0.0.10 → 0.0.11

package/build/files/index.d.ts

@@ -0,0 +1,9 @@
+import { createSchemaFile, interpolateEnv, interpolateEnvHook } from "./init";
+import { loadFile, loadFileSync, safeLoadFile, safeLoadFileSync } from "./load";
+import { parseStringSync } from "./parse";
+import { parseString } from "./parse";
+import { serialize, serializeAsync } from "./serialize";
+import { saveFile, saveFileSync } from "./save";
+import { SchemaFileError } from "./types";
+export type { ErrorFormatter, FileFormat, LoadOptions, ParseOptions, ParseParams, PreprocessContext, SafeResult, SaveOptions, SchemaFileErrorKind, SerializeOptions, SerializeStrategy, } from "./types";
+export { createSchemaFile, interpolateEnv, interpolateEnvHook, loadFile, loadFileSync, safeLoadFile, safeLoadFileSync, serialize, serializeAsync, parseString, parseStringSync, saveFileSync, saveFile, SchemaFileError };

package/build/files/index.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaFileError = exports.saveFile = exports.saveFileSync = exports.parseStringSync = exports.parseString = exports.serializeAsync = exports.serialize = exports.safeLoadFileSync = exports.safeLoadFile = exports.loadFileSync = exports.loadFile = exports.interpolateEnvHook = exports.interpolateEnv = exports.createSchemaFile = void 0;
+const init_1 = require("./init");
+Object.defineProperty(exports, "createSchemaFile", { enumerable: true, get: function () { return init_1.createSchemaFile; } });
+Object.defineProperty(exports, "interpolateEnv", { enumerable: true, get: function () { return init_1.interpolateEnv; } });
+Object.defineProperty(exports, "interpolateEnvHook", { enumerable: true, get: function () { return init_1.interpolateEnvHook; } });
+const load_1 = require("./load");
+Object.defineProperty(exports, "loadFile", { enumerable: true, get: function () { return load_1.loadFile; } });
+Object.defineProperty(exports, "loadFileSync", { enumerable: true, get: function () { return load_1.loadFileSync; } });
+Object.defineProperty(exports, "safeLoadFile", { enumerable: true, get: function () { return load_1.safeLoadFile; } });
+Object.defineProperty(exports, "safeLoadFileSync", { enumerable: true, get: function () { return load_1.safeLoadFileSync; } });
+const parse_1 = require("./parse");
+Object.defineProperty(exports, "parseStringSync", { enumerable: true, get: function () { return parse_1.parseStringSync; } });
+const parse_2 = require("./parse");
+Object.defineProperty(exports, "parseString", { enumerable: true, get: function () { return parse_2.parseString; } });
+const serialize_1 = require("./serialize");
+Object.defineProperty(exports, "serialize", { enumerable: true, get: function () { return serialize_1.serialize; } });
+Object.defineProperty(exports, "serializeAsync", { enumerable: true, get: function () { return serialize_1.serializeAsync; } });
+const save_1 = require("./save");
+Object.defineProperty(exports, "saveFile", { enumerable: true, get: function () { return save_1.saveFile; } });
+Object.defineProperty(exports, "saveFileSync", { enumerable: true, get: function () { return save_1.saveFileSync; } });
+const types_1 = require("./types");
+Object.defineProperty(exports, "SchemaFileError", { enumerable: true, get: function () { return types_1.SchemaFileError; } });

package/build/files/init.d.ts

@@ -0,0 +1,33 @@
+import * as z from "zod";
+import { LoadOptions, ParseOptions, SaveOptions, SerializeOptions } from "./types";
+/**
+ * Bind a schema and default options once, reuse everywhere.
+ * Per-call options are shallow-merged over the defaults.
+ */
+export declare function createSchemaFile<S extends z.ZodType>(schema: S, defaults?: {
+    load?: LoadOptions;
+    save?: SaveOptions;
+}): {
+    schema: S;
+    load: (filePath: string, o?: LoadOptions) => Promise<z.core.output<S>>;
+    loadSync: (filePath: string, o?: LoadOptions) => z.core.output<S>;
+    safeLoad: (filePath: string, o?: LoadOptions) => Promise<import("./types").SafeResult<z.core.output<S>>>;
+    safeLoadSync: (filePath: string, o?: LoadOptions) => import("./types").SafeResult<z.core.output<S>>;
+    parse: (text: string, o?: ParseOptions) => Promise<z.core.output<S>>;
+    save: (filePath: string, value: z.output<S>, o?: SaveOptions) => Promise<string>;
+    saveSync: (filePath: string, value: z.output<S>, o?: SaveOptions) => string;
+    serialize: (value: z.output<S>, o: SerializeOptions) => Promise<string>;
+};
+/**
+ * Recursively replace ${VAR} and ${VAR:-fallback} in string values.
+ * For a `preprocess` hook use interpolateEnvHook(): a hook's second argument is the
+ * PreprocessContext, which this function would read as `env`. Note results are strings,
+ * so use z.coerce.* in the schema for numeric/boolean fields filled from env vars.
+ */
+export declare function interpolateEnv(value: unknown, env?: Record<string, string | undefined>, options?: {
+    strict?: boolean;
+}): unknown;
+/** A `preprocess` hook that runs interpolateEnv over the parsed data: { preprocess: interpolateEnvHook() }. */
+export declare function interpolateEnvHook(env?: Record<string, string | undefined>, options?: {
+    strict?: boolean;
+}): (raw: unknown) => unknown;

package/build/files/init.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSchemaFile = createSchemaFile;
+exports.interpolateEnv = interpolateEnv;
+exports.interpolateEnvHook = interpolateEnvHook;
+const util_1 = require("./util");
+const serialize_1 = require("./serialize");
+const load_1 = require("./load");
+const save_1 = require("./save");
+const parse_1 = require("./parse");
+/**
+ * Bind a schema and default options once, reuse everywhere.
+ * Per-call options are shallow-merged over the defaults.
+ */
+function createSchemaFile(schema, defaults = {}) {
+    const l = (o) => (Object.assign(Object.assign({}, defaults.load), o));
+    const s = (o) => (Object.assign(Object.assign({}, defaults.save), o));
+    return {
+        schema,
+        load: (filePath, o) => (0, load_1.loadFile)(filePath, schema, l(o)),
+        loadSync: (filePath, o) => (0, load_1.loadFileSync)(filePath, schema, l(o)),
+        safeLoad: (filePath, o) => (0, load_1.safeLoadFile)(filePath, schema, l(o)),
+        safeLoadSync: (filePath, o) => (0, load_1.safeLoadFileSync)(filePath, schema, l(o)),
+        parse: (text, o) => (0, parse_1.parseString)(schema, text, l(o)),
+        save: (filePath, value, o) => (0, save_1.saveFile)(filePath, schema, value, s(o)),
+        saveSync: (filePath, value, o) => (0, save_1.saveFileSync)(filePath, schema, value, s(o)),
+        serialize: (value, o) => (0, serialize_1.serializeAsync)(schema, value, Object.assign(Object.assign({}, defaults.save), o)),
+    };
+}
+/**
+ * Recursively replace ${VAR} and ${VAR:-fallback} in string values.
+ * For a `preprocess` hook use interpolateEnvHook(): a hook's second argument is the
+ * PreprocessContext, which this function would read as `env`. Note results are strings,
+ * so use z.coerce.* in the schema for numeric/boolean fields filled from env vars.
+ */
+function interpolateEnv(value, env = process.env, options = {}) {
+    const pattern = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
+    const walk = (v) => {
+        if (typeof v === "string") {
+            return v.replace(pattern, (_m, name, fallback) => {
+                const found = env[name];
+                if (found !== undefined && found !== "")
+                    return found;
+                if (fallback !== undefined)
+                    return fallback;
+                if (options.strict)
+                    throw new Error(`Environment variable "${name}" is not set`);
+                return "";
+            });
+        }
+        if (Array.isArray(v))
+            return v.map(walk);
+        if ((0, util_1.isPlainObject)(v))
+            return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk(x)]));
+        return v;
+    };
+    return walk(value);
+}
+/** A `preprocess` hook that runs interpolateEnv over the parsed data: { preprocess: interpolateEnvHook() }. */
+function interpolateEnvHook(env = process.env, options = {}) {
+    return (raw) => interpolateEnv(raw, env, 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,54 @@
+"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 types_1 = require("./types");
+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 = {}) {
+        const opts = Object.assign(Object.assign({}, options), { filePath });
+        const { raw, format } = (0, util_1.toRaw)(yield (0, util_1.readTextAsync)(filePath, opts), opts);
+        return (0, util_1.validateAsync)(schema, yield (0, util_1.runPreprocess)(raw, format, opts), opts);
+    });
+}
+/** Synchronous variant. Fails if the schema contains async refinements/transforms. */
+function loadFileSync(filePath, schema, options = {}) {
+    const opts = Object.assign(Object.assign({}, options), { filePath });
+    const { raw, format } = (0, util_1.toRaw)((0, util_1.readTextSync)(filePath, opts), opts);
+    return (0, util_1.validateSync)(schema, (0, util_1.runPreprocessSync)(raw, format, opts), opts);
+}
+/** Like loadFile, but returns a result object instead of throwing SchemaFileError. */
+function safeLoadFile(filePath_1, schema_1) {
+    return __awaiter(this, arguments, void 0, function* (filePath, schema, options = {}) {
+        try {
+            return { success: true, data: yield loadFile(filePath, schema, options) };
+        }
+        catch (error) {
+            if (error instanceof types_1.SchemaFileError)
+                return { success: false, error };
+            throw error;
+        }
+    });
+}
+function safeLoadFileSync(filePath, schema, options = {}) {
+    try {
+        return { success: true, data: loadFileSync(filePath, schema, options) };
+    }
+    catch (error) {
+        if (error instanceof types_1.SchemaFileError)
+            return { success: false, error };
+        throw error;
+    }
+}

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,108 @@
+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;
+}
+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,28 @@
+import * as z from "zod";
+import { FileFormat, LoadOptions, ParseOptions, 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>;
+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;
+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 {};

package/build/files/util.js

@@ -0,0 +1,418 @@
+"use strict";
+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;
+    };
+})();
+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.label = label;
+exports.isPlainObject = isPlainObject;
+exports.decodeText = decodeText;
+exports.formatFromExtension = formatFromExtension;
+exports.resolveFormat = resolveFormat;
+exports.toRaw = toRaw;
+exports.readTextAsync = readTextAsync;
+exports.readTextSync = readTextSync;
+exports.runPreprocess = runPreprocess;
+exports.runPreprocessSync = runPreprocessSync;
+exports.validateAsync = validateAsync;
+exports.validateSync = validateSync;
+exports.toWireSync = toWireSync;
+exports.toWireAsync = toWireAsync;
+exports.render = render;
+exports.writeTextAsync = writeTextAsync;
+exports.writeTextSync = writeTextSync;
+const YAML = __importStar(require("yaml"));
+const z = __importStar(require("zod"));
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = require("node:fs");
+const types_1 = require("./types");
+const MISSING = Symbol("missing");
+function label(filePath) {
+    return filePath !== null && filePath !== void 0 ? filePath : "input";
+}
+function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+function isPlainObject(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+}
+function isNotFound(e) {
+    return (e === null || e === void 0 ? void 0 : e.code) === "ENOENT";
+}
+function decodeText(text, format, opts) {
+    var _a;
+    const src = opts.stripBom !== false && text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    if (src.trim() === "")
+        return opts.emptyValue;
+    try {
+        return format === "json" ? JSON.parse(src, (_a = opts.json) === null || _a === void 0 ? void 0 : _a.reviver) : YAML.parse(src, opts.yaml);
+    }
+    catch (cause) {
+        throw new types_1.SchemaFileError("parse", `Failed to parse ${label(opts.filePath)} as ${format.toUpperCase()}: ${errMsg(cause)}`, { filePath: opts.filePath, cause });
+    }
+}
+function formatFromExtension(filePath) {
+    return types_1.EXTENSIONS[node_path_1.default.extname(filePath).toLowerCase()];
+}
+/**
+ * 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.
+ */
+function resolveFormat(format, filePath, content) {
+    if (format && format !== "auto")
+        return format;
+    const byExt = filePath ? formatFromExtension(filePath) : undefined;
+    if (byExt)
+        return byExt;
+    if (content !== undefined)
+        return "yaml";
+    throw new types_1.SchemaFileError("format", `Cannot determine format for ${label(filePath)}; pass { format: "json" | "yaml" }`, { filePath });
+}
+function toRaw(text, opts) {
+    if (text === MISSING) {
+        return {
+            raw: "missingValue" in opts ? opts.missingValue : {},
+            format: resolveFormat(opts.format, opts.filePath, ""),
+        };
+    }
+    const format = resolveFormat(opts.format, opts.filePath, text);
+    return { raw: decodeText(text, format, opts), format };
+}
+function readTextAsync(filePath, opts) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        try {
+            return yield (0, promises_1.readFile)(filePath, { encoding: (_a = opts.encoding) !== null && _a !== void 0 ? _a : "utf8" });
+        }
+        catch (cause) {
+            if (opts.allowMissing && isNotFound(cause))
+                return MISSING;
+            throw new types_1.SchemaFileError("read", `Failed to read ${filePath}: ${errMsg(cause)}`, { filePath, cause });
+        }
+    });
+}
+function readTextSync(filePath, opts) {
+    var _a;
+    try {
+        return (0, node_fs_1.readFileSync)(filePath, { encoding: (_a = opts.encoding) !== null && _a !== void 0 ? _a : "utf8" });
+    }
+    catch (cause) {
+        if (opts.allowMissing && isNotFound(cause))
+            return MISSING;
+        throw new types_1.SchemaFileError("read", `Failed to read ${filePath}: ${errMsg(cause)}`, { filePath, cause });
+    }
+}
+function runPreprocess(raw, format, opts) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!opts.preprocess)
+            return raw;
+        try {
+            return yield opts.preprocess(raw, { format, filePath: opts.filePath });
+        }
+        catch (cause) {
+            throw preprocessError(cause, opts.filePath);
+        }
+    });
+}
+function runPreprocessSync(raw, format, opts) {
+    if (!opts.preprocess)
+        return raw;
+    let result;
+    try {
+        result = opts.preprocess(raw, { format, filePath: opts.filePath });
+    }
+    catch (cause) {
+        throw preprocessError(cause, opts.filePath);
+    }
+    if (result instanceof Promise) {
+        // Nobody will await it, so keep a rejection from surfacing as an unhandledRejection.
+        result.catch(() => {
+        });
+        throw new types_1.SchemaFileError("preprocess", "preprocess returned a Promise; use the async API instead", {
+            filePath: opts.filePath,
+        });
+    }
+    return result;
+}
+function preprocessError(cause, filePath) {
+    return new types_1.SchemaFileError("preprocess", `Preprocess failed for ${label(filePath)}: ${errMsg(cause)}`, {
+        filePath,
+        cause,
+    });
+}
+function zodError(kind, error, formatError, filePath) {
+    const pretty = (formatError !== null && formatError !== void 0 ? formatError : z.prettifyError)(error);
+    const verb = kind === "encode" ? "Encoding" : "Validation";
+    return new types_1.SchemaFileError(kind, `${verb} failed for ${label(filePath)}:\n${pretty}`, {
+        filePath,
+        issues: error.issues,
+        cause: error,
+    });
+}
+function validateAsync(schema, raw, opts) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const result = yield schema.safeParseAsync(raw, opts.parseParams);
+        if (result.success)
+            return result.data;
+        throw zodError("validate", result.error, opts.formatError, opts.filePath);
+    });
+}
+function validateSync(schema, raw, opts) {
+    let result;
+    try {
+        result = schema.safeParse(raw, opts.parseParams);
+    }
+    catch (cause) {
+        // e.g. "Encountered Promise during synchronous parse" for async refinements
+        throw new types_1.SchemaFileError("validate", `Synchronous validation failed for ${label(opts.filePath)}: ${errMsg(cause)} (try the async API)`, { filePath: opts.filePath, cause });
+    }
+    if (result.success)
+        return result.data;
+    throw zodError("validate", result.error, opts.formatError, opts.filePath);
+}
+function wireError(cause, strategy, opts) {
+    const kind = strategy === "encode" ? "encode" : "validate";
+    if (cause instanceof z.core.$ZodError)
+        return zodError(kind, cause, opts.formatError, opts.filePath);
+    const hint = cause instanceof z.core.$ZodAsyncError
+        ? " (try the async API)"
+        : cause instanceof z.core.$ZodEncodeError
+            ? ' (one-way .transform() cannot be encoded; use z.codec() or strategy: "parse")'
+            : "";
+    return new types_1.SchemaFileError(kind, `Could not ${strategy} value for ${label(opts.filePath)}: ${errMsg(cause)}${hint}`, {
+        filePath: opts.filePath,
+        cause,
+    });
+}
+function toWireSync(schema, value, opts) {
+    var _a;
+    const strategy = (_a = opts.strategy) !== null && _a !== void 0 ? _a : "encode";
+    if (strategy === "none")
+        return value;
+    try {
+        return strategy === "encode" ? z.encode(schema, value) : schema.parse(value);
+    }
+    catch (cause) {
+        throw wireError(cause, strategy, opts);
+    }
+}
+function toWireAsync(schema, value, opts) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const strategy = (_a = opts.strategy) !== null && _a !== void 0 ? _a : "encode";
+        if (strategy === "none")
+            return value;
+        try {
+            return strategy === "encode" ? yield z.encodeAsync(schema, value) : yield schema.parseAsync(value);
+        }
+        catch (cause) {
+            throw wireError(cause, strategy, opts);
+        }
+    });
+}
+function sortKeysDeep(v, compare) {
+    if (Array.isArray(v))
+        return v.map((x) => sortKeysDeep(x, compare));
+    if (isPlainObject(v)) {
+        return Object.fromEntries(Object.keys(v)
+            .sort(compare)
+            .map((k) => [k, sortKeysDeep(v[k], compare)]));
+    }
+    return v;
+}
+function render(data, opts) {
+    var _a, _b, _c, _d, _e;
+    const input = opts.sortKeys
+        ? sortKeysDeep(data, typeof opts.sortKeys === "function" ? opts.sortKeys : undefined)
+        : data;
+    const indent = (_a = opts.indent) !== null && _a !== void 0 ? _a : 2;
+    const trailingNewline = opts.trailingNewline !== false;
+    try {
+        if (opts.format === "json") {
+            const out = JSON.stringify(input, (_b = opts.json) === null || _b === void 0 ? void 0 : _b.replacer, indent);
+            if (out === undefined)
+                throw new Error("value is not JSON-serializable");
+            return trailingNewline ? `${out}\n` : out;
+        }
+        const doc = new YAML.Document(input, (_c = opts.yaml) === null || _c === void 0 ? void 0 : _c.document);
+        if ((_d = opts.yaml) === null || _d === void 0 ? void 0 : _d.comment) {
+            doc.commentBefore = opts.yaml.comment
+                .split("\n")
+                .map((line) => (line ? ` ${line}` : line))
+                .join("\n");
+        }
+        const out = doc.toString(Object.assign({ indent }, (_e = opts.yaml) === null || _e === void 0 ? void 0 : _e.stringify));
+        return trailingNewline ? out : out.replace(/\n$/, "");
+    }
+    catch (cause) {
+        throw new types_1.SchemaFileError("serialize", `Failed to serialize ${label(opts.filePath)} as ${opts.format.toUpperCase()}: ${errMsg(cause)}`, { filePath: opts.filePath, cause });
+    }
+}
+function tempPathFor(filePath) {
+    const rand = Math.random().toString(36).slice(2, 10);
+    return node_path_1.default.join(node_path_1.default.dirname(filePath), `.${node_path_1.default.basename(filePath)}.${process.pid}.${rand}.tmp`);
+}
+/**
+ * The rename in an atomic write replaces whatever sits at the path, so it has to target the file a
+ * symlink points at (even one that does not exist yet), or the link itself gets replaced.
+ */
+function atomicTargetAsync(filePath) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            return yield (0, promises_1.realpath)(filePath);
+        }
+        catch (_a) {
+            return (0, promises_1.readlink)(filePath).then((link) => node_path_1.default.resolve(node_path_1.default.dirname(filePath), link), () => filePath);
+        }
+    });
+}
+function atomicTargetSync(filePath) {
+    try {
+        return (0, node_fs_1.realpathSync)(filePath);
+    }
+    catch (_a) {
+        try {
+            return node_path_1.default.resolve(node_path_1.default.dirname(filePath), (0, node_fs_1.readlinkSync)(filePath));
+        }
+        catch (_b) {
+            return filePath;
+        }
+    }
+}
+/** The rename also swaps in a new file, so an explicit `mode` aside, keep the replaced file's permissions. */
+function preservedModeAsync(target, opts) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (opts.mode !== undefined)
+            return undefined;
+        return (0, promises_1.stat)(target).then((stats) => stats.mode & 0o777, () => undefined);
+    });
+}
+function preservedModeSync(target, opts) {
+    if (opts.mode !== undefined)
+        return undefined;
+    try {
+        return (0, node_fs_1.statSync)(target).mode & 0o777;
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+function writeTextAsync(filePath, text, opts) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        try {
+            if (opts.createDirs !== false)
+                yield (0, promises_1.mkdir)(node_path_1.default.dirname(filePath), { recursive: true });
+            if (opts.overwrite === false && (yield (0, promises_1.access)(filePath).then(() => true, () => false))) {
+                throw new types_1.SchemaFileError("write", `Refusing to overwrite existing file ${filePath}`, { filePath });
+            }
+            const base = { encoding: (_a = opts.encoding) !== null && _a !== void 0 ? _a : "utf8", mode: opts.mode };
+            if (opts.atomic === false) {
+                yield (0, promises_1.writeFile)(filePath, text, Object.assign(Object.assign({}, base), { flag: opts.overwrite === false ? "wx" : "w" }));
+                return;
+            }
+            const target = yield atomicTargetAsync(filePath);
+            const preserved = yield preservedModeAsync(target, opts);
+            const tmp = tempPathFor(target);
+            try {
+                yield (0, promises_1.writeFile)(tmp, text, Object.assign(Object.assign({}, base), { flag: "wx" }));
+                if (preserved !== undefined)
+                    yield (0, promises_1.chmod)(tmp, preserved);
+                yield (0, promises_1.rename)(tmp, target);
+            }
+            catch (e) {
+                yield (0, promises_1.unlink)(tmp).catch(() => {
+                });
+                throw e;
+            }
+        }
+        catch (cause) {
+            if (cause instanceof types_1.SchemaFileError)
+                throw cause;
+            throw new types_1.SchemaFileError("write", `Failed to write ${filePath}: ${errMsg(cause)}`, { filePath, cause });
+        }
+    });
+}
+function writeTextSync(filePath, text, opts) {
+    var _a;
+    try {
+        if (opts.createDirs !== false)
+            (0, node_fs_1.mkdirSync)(node_path_1.default.dirname(filePath), { recursive: true });
+        if (opts.overwrite === false && (0, node_fs_1.existsSync)(filePath)) {
+            throw new types_1.SchemaFileError("write", `Refusing to overwrite existing file ${filePath}`, { filePath });
+        }
+        const base = { encoding: (_a = opts.encoding) !== null && _a !== void 0 ? _a : "utf8", mode: opts.mode };
+        if (opts.atomic === false) {
+            (0, node_fs_1.writeFileSync)(filePath, text, Object.assign(Object.assign({}, base), { flag: opts.overwrite === false ? "wx" : "w" }));
+            return;
+        }
+        const target = atomicTargetSync(filePath);
+        const preserved = preservedModeSync(target, opts);
+        const tmp = tempPathFor(target);
+        try {
+            (0, node_fs_1.writeFileSync)(tmp, text, Object.assign(Object.assign({}, base), { flag: "wx" }));
+            if (preserved !== undefined)
+                (0, node_fs_1.chmodSync)(tmp, preserved);
+            (0, node_fs_1.renameSync)(tmp, target);
+        }
+        catch (e) {
+            try {
+                (0, node_fs_1.unlinkSync)(tmp);
+            }
+            catch (_b) {
+                /* ignore */
+            }
+            throw e;
+        }
+    }
+    catch (cause) {
+        if (cause instanceof types_1.SchemaFileError)
+            throw cause;
+        throw new types_1.SchemaFileError("write", `Failed to write ${filePath}: ${errMsg(cause)}`, { filePath, cause });
+    }
+}

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "@epsilon-asi/foundation",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "description": "",
   "mainDir": "./",
+  "types": "./build/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "files": [
+        "./build/files/index.d.ts"
+      ]
+    }
+  },
   "scripts": {
     "build": "tsc",
     "build:clean": "rm -rf ./build && npm run build",
@@ -50,6 +58,11 @@
       "import": "./build/index.js",
       "require": "./build/index.js"
     },
+    "./files": {
+      "types": "./build/files/index.d.ts",
+      "import": "./build/files/index.js",
+      "require": "./build/files/index.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -59,7 +72,9 @@
   ],
   "author": "",
   "license": "SEE LICENSE IN LICENSE",
-  "dependencies": {},
+  "dependencies": {
+    "yaml": "^2.9.1"
+  },
   "peerDependencies": {
     "zod": "^4.0.0"
   }