@epsilon-asi/foundation 0.0.11 → 0.0.12

package/build/files/types.d.ts

@@ -105,4 +105,29 @@ export interface SaveOptions extends Omit<SerializeOptions, "format" | "filePath
     /** 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/util.d.ts

@@ -1,8 +1,19 @@
 import * as z from "zod";
-import { FileFormat, LoadOptions, ParseOptions, SaveOptions, SerializeOptions } from "./types";
+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;
 /**
@@ -16,6 +27,9 @@ export declare function toRaw(text: string | typeof MISSING, opts: LoadOptions):
 };
 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>>;

package/build/files/util.js

@@ -47,12 +47,19 @@ var __importDefault = (this && this.__importDefault) || function (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;
@@ -65,6 +72,7 @@ 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");
@@ -81,6 +89,62 @@ function isPlainObject(v) {
     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";
 }
@@ -147,6 +211,19 @@ function readTextSync(filePath, opts) {
         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)
@@ -348,7 +425,7 @@ function writeTextAsync(filePath, text, opts) {
         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))) {
+            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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epsilon-asi/foundation",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "",
   "mainDir": "./",
   "types": "./build/index.d.ts",
@@ -31,10 +31,10 @@
     "testEnvironment": "node",
     "coverageThreshold": {
       "global": {
-        "branches": 80,
-        "functions": 80,
-        "lines": 80,
-        "statements": 80
+        "branches": 90,
+        "functions": 90,
+        "lines": 90,
+        "statements": 90
       }
     },
     "testMatch": [
@@ -73,6 +73,7 @@
   "author": "",
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
+    "dotenv": "^17.4.2",
     "yaml": "^2.9.1"
   },
   "peerDependencies": {