@epsilon-asi/foundation 0.0.12 → 0.0.13

package/build/files/layered.d.ts

@@ -2,7 +2,8 @@ import * as z from "zod";
 import { DiscoverOptions, FileLayer, LayeredLoadOptions, LayeredResult, LoadOptions, SafeResult } from "./types";
 /**
  * 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.
+ * `startDir` upwards, then among `fallbacks`, after any `extraFiles`. Results are ordered highest
+ * precedence first.
  */
 export declare function discoverLayers(fileName: string, options?: DiscoverOptions): Promise<FileLayer[]>;
 export declare function discoverLayersSync(fileName: string, options?: DiscoverOptions): FileLayer[];
@@ -15,7 +16,7 @@ export declare function loadMergedFiles<S extends z.ZodType>(filePaths: readonly
 export declare function loadMergedFilesSync<S extends z.ZodType>(filePaths: readonly string[], schema: S, options?: LoadOptions): z.output<S>;
 /**
  * Discover every `fileName` layer (see discoverLayers), merge them and validate.
- * Precedence: start directory > nearer ancestors > farther ancestors > fallbacks, in order.
+ * Precedence: extraFiles (in order) > start directory > nearer ancestors > farther ancestors > fallbacks (in order).
  * With no layers found, the schema validates `{}`, so its defaults apply.
  */
 export declare function loadLayeredFile<S extends z.ZodType>(fileName: string, schema: S, options?: LayeredLoadOptions): Promise<LayeredResult<z.output<S>>>;

package/build/files/layered.js

@@ -26,38 +26,44 @@ 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.
+ * Every place `fileName` may live, highest precedence first: the extra files, 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;
+    var _a, _b, _c;
     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 = [];
+    const all = ((_b = options.extraFiles) !== null && _b !== void 0 ? _b : []).map((extra) => ({
+        filePath: node_path_1.default.resolve(start, (0, util_1.expandHome)(extra)),
+        origin: "extra",
+    }));
     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 : []) {
+    for (const fallback of (_c = options.fallbacks) !== null && _c !== void 0 ? _c : []) {
         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)));
 }
+/** Extra files are kept whether or not they exist, so a missing one is reported when it loads. */
+const isRequested = (layer) => layer.origin === "extra";
 /**
  * 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.
+ * `startDir` upwards, then among `fallbacks`, after any `extraFiles`. 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)));
+        const present = yield Promise.all(all.map((layer) => isRequested(layer) || (0, util_1.pathExists)(layer.filePath)));
         return all.filter((_, i) => present[i]);
     });
 }
 function discoverLayersSync(fileName, options = {}) {
-    return candidates(fileName, options).filter(({ filePath }) => (0, node_fs_1.existsSync)(filePath));
+    return candidates(fileName, options).filter((layer) => isRequested(layer) || (0, node_fs_1.existsSync)(layer.filePath));
 }
 /** A layer must be a mapping to merge; an empty file contributes nothing. */
 function asLayer(raw, filePath) {
@@ -87,7 +93,7 @@ function loadMergedFilesSync(filePaths, schema, options = {}) {
 }
 /**
  * Discover every `fileName` layer (see discoverLayers), merge them and validate.
- * Precedence: start directory > nearer ancestors > farther ancestors > fallbacks, in order.
+ * Precedence: extraFiles (in order) > 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) {

package/build/files/types.d.ts

@@ -105,8 +105,8 @@ 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";
+/** Where a layer came from: an extra file, the start directory, one of its ancestors, or a fallback path. */
+export type LayerOrigin = "extra" | "local" | "ancestor" | "fallback";
 /** One file discovered by discoverLayers(). */
 export interface FileLayer {
     /** Absolute path of the file. */
@@ -114,6 +114,12 @@ export interface FileLayer {
     origin: LayerOrigin;
 }
 export interface DiscoverOptions {
+    /**
+     * Additional files to layer in, ranked above everything discovered; index 0 has the highest
+     * precedence. Relative paths resolve against `startDir`, and `~/` is expanded. They are always
+     * included, so loading a missing one fails with a "read" error unless `allowMissing` is set.
+     */
+    extraFiles?: readonly string[];
     /** Directory the upward walk starts from. Default: process.cwd(). */
     startDir?: string;
     /** Last directory the walk visits (inclusive). Default: the filesystem root. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epsilon-asi/foundation",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "description": "",
   "mainDir": "./",
   "types": "./build/index.d.ts",