@epsilon-asi/foundation 0.0.10 → 0.0.12

package/build/files/util.js

@@ -0,0 +1,495 @@
+"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.deepMerge = deepMerge;
+exports.expandHome = expandHome;
+exports.pathExists = pathExists;
+exports.safely = safely;
+exports.safelySync = safelySync;
+exports.decodeText = decodeText;
+exports.formatFromExtension = formatFromExtension;
+exports.resolveFormat = resolveFormat;
+exports.toRaw = toRaw;
+exports.readTextAsync = readTextAsync;
+exports.readTextSync = readTextSync;
+exports.readRawAsync = readRawAsync;
+exports.readRawSync = readRawSync;
+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_os_1 = __importDefault(require("node:os"));
+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;
+}
+/**
+ * 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.
+ */
+function deepMerge(...sources) {
+    const result = {};
+    for (const source of sources) {
+        if (!isPlainObject(source))
+            continue;
+        for (const [key, value] of Object.entries(source)) {
+            if (value === undefined)
+                continue;
+            const existing = result[key];
+            // defineProperty, not assignment: a parsed "__proto__" key must stay data, not swap the prototype.
+            Object.defineProperty(result, key, {
+                value: isPlainObject(existing) && isPlainObject(value) ? deepMerge(existing, value) : value,
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
+        }
+    }
+    return result;
+}
+/** Replace a leading `~` with the current user's home directory. */
+function expandHome(filePath) {
+    if (filePath === "~")
+        return node_os_1.default.homedir();
+    return /^~[\\/]/.test(filePath) ? node_path_1.default.join(node_os_1.default.homedir(), filePath.slice(2)) : filePath;
+}
+function pathExists(filePath) {
+    return (0, promises_1.access)(filePath).then(() => true, () => false);
+}
+/** Run `run`, turning a thrown SchemaFileError into a failed SafeResult. Other errors propagate. */
+function safely(run) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            return { success: true, data: yield run() };
+        }
+        catch (error) {
+            if (error instanceof types_1.SchemaFileError)
+                return { success: false, error };
+            throw error;
+        }
+    });
+}
+function safelySync(run) {
+    try {
+        return { success: true, data: run() };
+    }
+    catch (error) {
+        if (error instanceof types_1.SchemaFileError)
+            return { success: false, error };
+        throw error;
+    }
+}
+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 });
+    }
+}
+/** Read, decode and preprocess a file: everything loadFile does short of validation. */
+function readRawAsync(filePath, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const opts = Object.assign(Object.assign({}, options), { filePath });
+        const { raw, format } = toRaw(yield readTextAsync(filePath, opts), opts);
+        return runPreprocess(raw, format, opts);
+    });
+}
+function readRawSync(filePath, options) {
+    const opts = Object.assign(Object.assign({}, options), { filePath });
+    const { raw, format } = toRaw(readTextSync(filePath, opts), opts);
+    return runPreprocessSync(raw, format, opts);
+}
+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 pathExists(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) {
+                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.12",
   "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",
@@ -23,10 +31,10 @@
     "testEnvironment": "node",
     "coverageThreshold": {
       "global": {
-        "branches": 80,
-        "functions": 80,
-        "lines": 80,
-        "statements": 80
+        "branches": 90,
+        "functions": 90,
+        "lines": 90,
+        "statements": 90
       }
     },
     "testMatch": [
@@ -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,10 @@
   ],
   "author": "",
   "license": "SEE LICENSE IN LICENSE",
-  "dependencies": {},
+  "dependencies": {
+    "dotenv": "^17.4.2",
+    "yaml": "^2.9.1"
+  },
   "peerDependencies": {
     "zod": "^4.0.0"
   }