@fulmenhq/tsfulmen 0.3.2 → 0.4.0

package/dist/config/index.d.ts

@@ -123,22 +123,29 @@ interface ConfigPathOptions {
 }
 
 /**
- * Options for loading configuration
+ * Fields common to all `loadConfig` call shapes (independent of how the
+ * defaults layer is supplied).
  */
-interface LoadConfigOptions {
+interface BaseLoadConfigOptions {
     /**
      * Application identifier for resolving user config paths
      */
     identity: AppIdentifier;
     /**
-     * Absolute path to the defaults configuration file
-     * This file MUST exist
+     * Optional absolute path to a schema file for validation.
+     *
+     * If both `schemaPath` and inline `schema` are given, `schema` takes precedence.
      */
-    defaultsPath: string;
+    schemaPath?: string;
     /**
-     * Optional absolute path to a schema file for validation
+     * Inline schema content (JSON or YAML string) for validation.
+     *
+     * Provide this instead of `schemaPath` when the schema is embedded at build
+     * time. Note: schema validation still requires the JSON-Schema metaschema,
+     * which tsfulmen currently loads from disk — full in-binary config validation
+     * lands with the asset-embedding work (Phase 2 / v0.4.0).
      */
-    schemaPath?: string;
+    schema?: string;
     /**
      * Optional environment variable prefix for overrides
      * Defaults to identity.app.env_prefix if available, otherwise identity.app upper-cased
@@ -157,14 +164,56 @@ interface LoadConfigOptions {
      */
     includeEnvVarReport?: boolean;
 }
+/**
+ * Options for loading configuration from a defaults **file path**.
+ *
+ * This is the original, patch-stable shape: `defaultsPath` is required and
+ * typed `string`. For build-time embedded defaults (no file on disk), use
+ * {@link LoadInlineConfigOptions} instead.
+ */
+interface LoadConfigOptions extends BaseLoadConfigOptions {
+    /**
+     * Absolute path to the defaults configuration file. This file MUST exist.
+     */
+    defaultsPath: string;
+    /** Mutually exclusive with {@link LoadInlineConfigOptions.defaults}. */
+    defaults?: never;
+}
+/**
+ * Options for loading configuration from **inline defaults** content.
+ *
+ * Provide a pre-parsed `defaults` object instead of a `defaultsPath` when the
+ * defaults are embedded at build time (e.g. a `bun --compile` single-file
+ * binary, where the defaults file is not on disk). Avoids the temp-file dance
+ * of writing embedded content out just to pass a path.
+ */
+interface LoadInlineConfigOptions extends BaseLoadConfigOptions {
+    /**
+     * Inline defaults content as a pre-parsed object.
+     */
+    defaults: Record<string, unknown>;
+    /** Mutually exclusive with {@link LoadConfigOptions.defaultsPath}. */
+    defaultsPath?: never;
+}
 /**
  * Metadata about the loaded configuration
  */
 interface ConfigMetadata {
     /**
-     * Path to the defaults file used
+     * Path to the defaults file used.
+     *
+     * Empty string (`""`) when inline `defaults` was provided (there is no backing
+     * file). Path-based callers always get the path they passed — the static type
+     * stays `string` for patch compatibility. Use `defaultsSource` to distinguish
+     * the inline case unambiguously.
      */
     defaultsPath: string;
+    /**
+     * Origin of the defaults layer: a file path (`"path"`) or inline `defaults`
+     * content (`"inline"`). Optional/additive — present from the inline-defaults
+     * feature onward.
+     */
+    defaultsSource?: "path" | "inline";
     /**
      * Path to the user config file used (null if not found)
      */
@@ -190,9 +239,16 @@ interface ConfigMetadata {
      */
     schema: {
         /**
-         * Path to the schema file used (if any)
+         * Path to the schema file used (null when none, or when inline `schema`
+         * content was provided — inline has no backing file).
          */
         path: string | null;
+        /**
+         * Origin of the schema used for validation: a file path (`"path"`) or inline
+         * `schema` content (`"inline"`), or `null` when no schema was provided.
+         * Optional/additive.
+         */
+        source?: "path" | "inline" | null;
         /**
          * Whether validation was performed
          */
@@ -214,11 +270,13 @@ interface LoadedConfig<T> {
 }
 /**
  * Load configuration using the Three-Layer pattern:
- * 1. Defaults (required)
+ * 1. Defaults (required) — from a file path ({@link LoadConfigOptions}) or
+ *    inline content ({@link LoadInlineConfigOptions})
  * 2. User Config (optional, XDG-compliant)
  * 3. Environment Variables (optional, prefix-based)
  */
 declare function loadConfig<T>(options: LoadConfigOptions): Promise<LoadedConfig<T>>;
+declare function loadConfig<T>(options: LoadInlineConfigOptions): Promise<LoadedConfig<T>>;
 
 /**
  * Config Path API - implements Fulmen Config Path Standard
@@ -277,4 +335,4 @@ declare function resolveConfigPath(filename: string, searchPaths: string[], opti
  */
 declare const VERSION = "0.1.0";
 
-export { type AppIdentifier, type ConfigMetadata, ConfigPathError, type ConfigPathOptions, ConfigValidationError, type EnvAliasConflict, type LoadConfigOptions, type LoadedConfig, type PlatformDirs, type ResolveEnvAliasesResult, VERSION, type XDGBaseDirs, ensureDirExists, getAppCacheDir, getAppConfigDir, getAppDataDir, getConfigSearchPaths, getFulmenCacheDir, getFulmenConfigDir, getFulmenDataDir, getXDGBaseDirs, loadConfig, resolveConfigPath, resolveEnvAliases };
+export { type AppIdentifier, type BaseLoadConfigOptions, type ConfigMetadata, ConfigPathError, type ConfigPathOptions, ConfigValidationError, type EnvAliasConflict, type LoadConfigOptions, type LoadInlineConfigOptions, type LoadedConfig, type PlatformDirs, type ResolveEnvAliasesResult, VERSION, type XDGBaseDirs, ensureDirExists, getAppCacheDir, getAppConfigDir, getAppDataDir, getConfigSearchPaths, getFulmenCacheDir, getFulmenConfigDir, getFulmenDataDir, getXDGBaseDirs, loadConfig, resolveConfigPath, resolveEnvAliases };