configorama 0.6.18 → 0.7.0

package/README.md

@@ -229,10 +229,10 @@ asyncJSValue: ${file(./async-value.js)}
 # resolves to 'asyncval'
 ```
 
-`${file(./asyncValue.js)}` will call into `async-value` and run/resolve the async function with values. These values can be strings, objects, arrays, whatever.
+`${file(./async-value.js)}` will call into `async-value` and run/resolve the async function. Return values can be strings, objects, arrays, etc.
 
 ```js
-async function fetchSecretsFromRemoteStore(config) {
+async function fetchSecretsFromRemoteStore() {
   await delay(1000)
   return 'asyncval'
 }
@@ -240,6 +240,82 @@ async function fetchSecretsFromRemoteStore(config) {
 module.exports = fetchSecretsFromRemoteStore
 ```
 
+#### Passing arguments to functions
+
+You can pass arguments from your config to JavaScript/TypeScript functions:
+
+```yml
+foo: bar
+baz:
+  qux: quux
+
+# Pass resolved values as arguments
+secrets: ${file(./fetch-secrets.js, ${self:foo}, ${self:baz})}
+```
+
+Arguments are passed in order, with the config context always last:
+
+```js
+/**
+ * @param {string} foo - First arg from YAML ('bar')
+ * @param {object} baz - Second arg from YAML ({ qux: 'quux' })
+ * @param {import('configorama').ConfigContext} ctx - Config context (always last)
+ */
+async function fetchSecrets(foo, baz, ctx) {
+  console.log(foo)  // 'bar'
+  console.log(baz)  // { qux: 'quux' }
+  console.log(ctx.originalConfig)  // Original unresolved config
+  console.log(ctx.currentConfig)   // Current partially-resolved config
+  console.log(ctx.options)         // Options passed to configorama
+
+  return { secret: 'value' }
+}
+
+module.exports = fetchSecrets
+```
+
+#### ConfigContext
+
+The `ctx` parameter (always the last argument) provides access to:
+
+| Property | Description |
+|----------|-------------|
+| `originalConfig` | The original unresolved configuration object |
+| `currentConfig` | The current (partially resolved) configuration |
+| `options` | Options passed to configorama (populates `${opt:xyz}` variables) |
+
+TypeScript users can import the type:
+
+```typescript
+import type { ConfigContext } from 'configorama'
+
+async function fetchSecrets(
+  foo: string,
+  baz: { qux: string },
+  ctx: ConfigContext
+): Promise<string> {
+  // Full type support for ctx properties
+  return 'secret-value'
+}
+
+export = fetchSecrets
+```
+
+#### Functions without arguments
+
+If you don't need arguments, the function still receives `ctx` as its only parameter:
+
+```js
+// No args - ctx is the only parameter
+async function getSecrets(ctx) {
+  return ctx.options.stage === 'prod'
+    ? 'prod-secret'
+    : 'dev-secret'
+}
+
+module.exports = getSecrets
+```
+
 ### TypeScript file references
 
 Execute TypeScript files using tsx (recommended) or ts-node.

package/cli.js

@@ -184,6 +184,7 @@ configorama(inputFile, options)
       content: error.message,
       type: 'error',
     })
+    console.log('error', error)
     console.log(errorMsg)
     if (argv.debug) {
       console.error(error.stack)

package/index.d.ts

@@ -1,45 +1,98 @@
 // Type definitions for configorama
 // Project: https://github.com/DavidWells/configorama
-// Definitions by: Claude AI
 
-// Export the variable validation types
+// Re-export variable validation types
 export * from './src/types'
 
-// Main configorama function (async)
-export default function configorama(
-  configPath: string, 
-  options?: {
-    options?: Record<string, any>
-    variableSources?: Record<string, any>
-    [key: string]: any
-  }
-): Promise<any>
+export interface ConfigoramaSettings {
+  /** Options to populate for ${opt:xyz}. These could be CLI flags */
+  options?: Record<string, any>
+  /** Regex of variable syntax */
+  syntax?: string
+  /** cwd of config. Needed if raw object passed in instead of file path */
+  configDir?: string
+  /** Array of custom variable sources */
+  variableSources?: any[]
+  /** Object of custom filters */
+  filters?: Record<string, Function>
+  /** Object of custom functions */
+  functions?: Record<string, Function>
+  /** Allow unknown variables to pass through without throwing errors */
+  allowUnknownVars?: boolean
+  /** Allow undefined values to pass through without throwing errors */
+  allowUndefinedValues?: boolean
+  /** Values passed into .js config files if user using javascript config */
+  dynamicArgs?: object | Function
+  /** Return both config and metadata about variables found */
+  returnMetadata?: boolean
+  /** Keys to merge in arrays of objects */
+  mergeKeys?: string[]
+  /** Map of file paths to override */
+  filePathOverrides?: Record<string, string>
+}
+
+export interface ConfigoramaResult<T = any> {
+  /** The variable syntax pattern used */
+  variableSyntax: RegExp
+  /** Map of variable types found */
+  variableTypes: Record<string, any>
+  /** The resolved configuration object */
+  config: T
+  /** The original unresolved configuration */
+  originalConfig: any
+  /** Metadata about variables found and resolved */
+  metadata: any
+  /** Resolution history per path for debugging */
+  resolutionHistory: any
+}
+
+/**
+ * Context passed to JS/TS/ESM config file functions
+ * Used when config files export a function: `export default function(ctx) { ... }`
+ */
+export interface ConfigContext<T = any> {
+  /** The original unresolved configuration object */
+  originalConfig: T
+  /** The current (partially resolved) configuration object */
+  currentConfig: T
+  /** Options passed to configorama (populates ${opt:xyz} variables) */
+  options: Record<string, any>
+}
 
-// Sync version
-export function sync(
-  configPath: string,
-  options?: {
-    options?: Record<string, any>
-    variableSources?: Record<string, any>
-    [key: string]: any
-  }
-): any
-
-// Generic typed versions for better TypeScript experience
-export function configorama<T>(
-  configPath: string,
-  options?: {
-    options?: Record<string, any>
-    variableSources?: Record<string, any>
-    [key: string]: any
-  }
+/** Configorama async API - returns resolved config */
+declare function configorama<T = any>(
+  configPathOrObject: string | object,
+  settings?: ConfigoramaSettings & { returnMetadata?: false }
 ): Promise<T>
 
-export function sync<T>(
-  configPath: string,
-  options?: {
-    options?: Record<string, any>
-    variableSources?: Record<string, any>
-    [key: string]: any
-  }
-): T
+/** Configorama async API - returns config with metadata */
+declare function configorama<T = any>(
+  configPathOrObject: string | object,
+  settings: ConfigoramaSettings & { returnMetadata: true }
+): Promise<ConfigoramaResult<T>>
+
+export default configorama
+
+/** Configorama sync API */
+export function sync<T = any>(
+  configPathOrObject: string | object,
+  settings?: ConfigoramaSettings
+): T
+
+/** Analyze config variables without resolving them */
+export function analyze(
+  configPathOrObject: string | object,
+  settings?: ConfigoramaSettings
+): Promise<any>
+
+/** Format utilities for parsing various config formats */
+export const format: {
+  yaml: any
+  json: any
+  toml: any
+  ini: any
+  hcl: any
+}
+
+/** The Configorama class for advanced usage */
+export const Configorama: any

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "configorama",
-  "version": "0.6.18",
+  "version": "0.7.0",
   "description": "Variable support for configuration files",
   "main": "src/index.js",
   "types": "index.d.ts",
@@ -11,6 +11,7 @@
   "files": [
     "cli.js",
     "src",
+    "types",
     "index.d.ts",
     "package.json",
     "package-lock.json",
@@ -29,6 +30,10 @@
     "test:api": "uvu tests/api api.test.js",
     "test:lib": "uvu src \".*\\.test.js$\"",
     "watch": "watchlist tests -- npm test",
+    "typecheck": "tsc --noEmit",
+    "types": "tsc",
+    "types:watch": "tsc --watch",
+    "prepublishOnly": "npm run types",
     "publish": "git push origin && git push origin --tags",
     "release:patch": "npm version patch && npm publish",
     "release:minor": "npm version minor && npm publish",
@@ -74,12 +79,13 @@
     "lodash.split": "^4.4.2",
     "minimist": "^1.2.8",
     "promise.prototype.finally": "^3.1.8",
-    "safe-chalk": "^1.0.0",
+    "safe-chalk": "^1.0.4",
     "subscript": "^9.1.0",
     "sync-rpc": "^1.3.6",
     "traverse": "^0.6.8"
   },
   "devDependencies": {
+    "@types/node": "^24.10.1",
     "markdown-magic": "^3.4.0",
     "tsx": "^4.7.0",
     "typescript": "^5.8.3",

package/src/index.js

@@ -4,21 +4,39 @@ const enrichMetadata = require('./utils/parsing/enrichMetadata')
 
 module.exports.Configorama = Configorama
 
+/**
+ * @typedef {Object} ConfigoramaSettings
+ * @property {Object.<string, any>} [options] - options to populate for ${opt:xyz}. These could be CLI flags
+ * @property {string} [syntax] - Regex of variable syntax
+ * @property {string} [configDir] - cwd of config. Needed if raw object passed in instead of file path
+ * @property {Array} [variableSources] - array of custom variable sources
+ * @property {Object.<string, Function>} [filters] - Object of custom filters
+ * @property {Object.<string, Function>} [functions] - Object of custom functions
+ * @property {boolean} [allowUnknownVars] - allow unknown variables to pass through without throwing errors
+ * @property {boolean} [allowUndefinedValues] - allow undefined values to pass through without throwing errors
+ * @property {Object|Function} [dynamicArgs] - values passed into .js config files if user using javascript config
+ * @property {boolean} [returnMetadata] - return both config and metadata about variables found
+ * @property {string[]} [mergeKeys] - keys to merge in arrays of objects
+ * @property {Object.<string, string>} [filePathOverrides] - map of file paths to override
+ */
+
+/**
+ * @template [T=any]
+ * @typedef {Object} ConfigoramaResult
+ * @property {RegExp} variableSyntax - The variable syntax pattern used
+ * @property {Object.<string, any>} variableTypes - Map of variable types found
+ * @property {T} config - The resolved configuration object
+ * @property {Object} originalConfig - The original unresolved configuration
+ * @property {Object} metadata - Metadata about variables found and resolved
+ * @property {Object} resolutionHistory - Resolution history per path for debugging
+ */
+
 /**
  * Configorama async API
- * @param  {string|object} configPathOrObject - Path to config file or raw javascript config object
- * @param {object}  [settings] Information about the user.
- * @param {object}  [settings.options] - options to populate for ${opt:xyz}. These could be CLI flags
- * @param {string}  [settings.syntax] - Regex of variable syntax
- * @param {string}  [settings.configDir] - cwd of config. Needed if raw object passed in instead of file path
- * @param {array}   [settings.variableSources] - array of custom variable sources
- * @param {object}  [settings.filters] - Object of of custom filters
- * @param {object}  [settings.functions] - Object of of custom functions
- * @param {boolean} [settings.allowUnknownVars] - allow unknown variables to pass through without throwing errors
- * @param {boolean} [settings.allowUndefinedValues] - allow undefined values to pass through without throwing errors
- * @param {object|function} [settings.dynamicArgs] - values passed into .js config files if user using javascript config.
- * @param {boolean} [settings.returnMetadata] - return both config and metadata about variables found
- * @return {Promise} resolved configuration or {config, metadata} if returnMetadata is true
+ * @template [T=any]
+ * @param {string|Object} configPathOrObject - Path to config file or raw javascript config object
+ * @param {ConfigoramaSettings} [settings] - Configuration settings
+ * @returns {Promise<T | ConfigoramaResult<T>>} resolved configuration or {config, metadata} if returnMetadata is true
  */
 module.exports = async (configPathOrObject, settings = {}) => {
   const instance = new Configorama(configPathOrObject, settings)
@@ -69,6 +87,13 @@ module.exports = async (configPathOrObject, settings = {}) => {
   return config
 }
 
+/**
+ * Configorama sync API
+ * @template [T=any]
+ * @param {string|Object} configPathOrObject - Path to config file or raw javascript config object
+ * @param {ConfigoramaSettings} [settings] - Configuration settings
+ * @returns {T} resolved configuration object
+ */
 module.exports.sync = (configPathOrObject, settings = {}) => {
   const _settings = settings || {}
   if (_settings.dynamicArgs && typeof _settings.dynamicArgs === 'function') {
@@ -100,5 +125,8 @@ module.exports.analyze = async (configPathOrObject, settings = {}) => {
   return instance.init(options)
 }
 
-// Export format utilities
+/**
+ * Format utilities for parsing various config formats
+ * @type {Object}
+ */
 module.exports.format = parsers