configorama 0.6.3 → 0.6.5

package/README.md

@@ -11,36 +11,44 @@ Configorama extends your configuration with a powerful variable system. It resol
 - CLI options
 - ENV variables
 - File references
-- Other Key/values in config
+- TypeScript file references
+- Self references (other keys/values in config)
+- Git references
+- Cron values
 - Async/sync JS functions
+- Filters (experimental)
+- Functions (experimental)
 - Any source you'd like...
 
 See [tests](https://github.com/DavidWells/configorama/tree/master/tests) for more examples.
 
 ## Table of Contents
-<!-- ⛔️ AUTO-GENERATED-CONTENT:START (TOC:collapse=true&collapseText=Click to expand) -->
+<!-- doc-gen {TOC} collapse=true collapseText="Click to expand" -->
 <details>
 <summary>Click to expand</summary>
 
 - [About](#about)
 - [Usage](#usage)
 - [Variable Sources](#variable-sources)
-  * [Environment variables](#environment-variables)
-  * [CLI option flags](#cli-option-flags)
-  * [Self references](#self-references)
-  * [File references](#file-references)
-  * [Sync/Async file references](#syncasync-file-references)
-  * [Git references](#git-references)
-  * [Filters (experimental)](#filters-experimental)
-  * [Functions (experimental)](#functions-experimental)
-  * [More Examples](#more-examples)
+  - [Environment variables](#environment-variables)
+  - [CLI option flags](#cli-option-flags)
+  - [Self references](#self-references)
+  - [File references](#file-references)
+  - [Sync/Async file references](#syncasync-file-references)
+  - [TypeScript file references](#typescript-file-references)
+  - [Git references](#git-references)
+  - [Cron Values](#cron-values)
+  - [Filters (experimental)](#filters-experimental)
+  - [Functions (experimental)](#functions-experimental)
+  - [More Examples](#more-examples)
 - [Custom Variable Sources](#custom-variable-sources)
 - [FAQ](#faq)
 - [Whats new](#whats-new)
+- [Alt libs](#alt-libs)
 - [Inspiration](#inspiration)
 
 </details>
-<!-- ⛔️ AUTO-GENERATED-CONTENT:END -->
+<!-- end-doc-gen -->
 
 ## Usage
 
@@ -157,6 +165,162 @@ async function fetchSecretsFromRemoteStore(config) {
 module.exports = fetchSecretsFromRemoteStore
 ```
 
+### TypeScript file references
+
+Configure with full TypeScript support using modern tsx execution engine with ts-node fallback.
+
+```yml
+# TypeScript configuration object
+config: ${file(./config.ts)}
+
+# TypeScript async function
+secrets: ${file(./async-secrets.ts)}
+
+# Specific property from TypeScript export
+database: ${file(./config.ts):database}
+```
+
+**TypeScript Object Export:**
+
+```typescript
+/* typescript-config.ts */
+interface DatabaseConfig {
+  host: string;
+  port: number;
+  database: string;
+  ssl: boolean;
+}
+
+interface ApiConfig {
+  baseUrl: string;
+  timeout: number;
+  retries: number;
+}
+
+interface ConfigObject {
+  environment: string;
+  database: DatabaseConfig;
+  api: ApiConfig;
+  features: {
+    enableNewFeature: boolean;
+    debugMode: boolean;
+  };
+}
+
+function createConfig(): ConfigObject {
+  return {
+    environment: '${opt:stage, "development"}',
+    database: {
+      host: '${env:DB_HOST, "localhost"}',
+      port: parseInt('${env:DB_PORT, "5432"}'),
+      database: '${env:DB_NAME, "myapp"}',
+      ssl: '${env:NODE_ENV}' === 'production'
+    },
+    api: {
+      baseUrl: '${env:API_BASE_URL, "http://localhost:3000"}',
+      timeout: 5000,
+      retries: 3
+    },
+    features: {
+      enableNewFeature: '${opt:stage}' === 'production',
+      debugMode: '${env:DEBUG, "false"}' === 'true'
+    }
+  }
+}
+
+export = createConfig
+```
+
+**TypeScript Async Function:**
+
+```typescript
+/* typescript-async.ts */
+interface SecretStore {
+  apiKey: string;
+  dbPassword: string;
+  jwtSecret: string;
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+async function fetchSecretsFromVault(): Promise<SecretStore> {
+  console.log('Fetching secrets from vault...')
+  
+  // Simulate async operations like fetching from AWS Secrets Manager, HashiCorp Vault, etc.
+  await delay(100)
+  
+  return {
+    apiKey: process.env.API_KEY || 'dev-api-key',
+    dbPassword: process.env.DB_PASSWORD || 'dev-password',
+    jwtSecret: process.env.JWT_SECRET || 'dev-jwt-secret'
+  }
+}
+
+export = fetchSecretsFromVault
+```
+
+**Complete Example Configuration:**
+
+```yml
+# config-with-typescript.yml
+service: my-awesome-app
+
+# Load configuration from TypeScript file
+provider: ${file(./typescript-config.ts)}
+
+# Load secrets asynchronously from TypeScript file
+secrets: ${file(./typescript-async.ts)}
+
+# Mix TypeScript with other configuration
+custom:
+  stage: ${opt:stage, "dev"}
+  region: ${opt:region, "us-east-1"}
+  
+  # You can also use TypeScript files for specific sections
+  databaseConfig: ${file(./typescript-config.ts):database}
+  
+  # Environment-specific overrides
+  stageVariables:
+    dev:
+      logLevel: debug
+    prod:
+      logLevel: info
+
+# Regular configuration values
+resources:
+  description: "Configuration loaded with TypeScript support"
+  timestamp: ${timestamp}
+  
+functions:
+  hello:
+    handler: handler.hello
+    environment:
+      LOG_LEVEL: ${self:custom.stageVariables.${self:custom.stage}.logLevel}
+      DB_HOST: ${self:provider.database.host}
+      API_KEY: ${self:secrets.apiKey}
+```
+
+**Installation Requirements:**
+
+TypeScript support requires either `tsx` (recommended) or `ts-node`:
+
+```bash
+# Recommended: Modern, fast TypeScript execution
+npm install tsx --save-dev
+
+# Alternative: Traditional ts-node approach
+npm install ts-node typescript --save-dev
+```
+
+**Features:**
+- Modern tsx execution (fast, no compilation) with ts-node fallback
+- Support for both sync and async TypeScript functions
+- Function argument passing via `dynamicArgs`
+- Full TypeScript interface support
+- Comprehensive error handling with helpful dependency messages
+
 ### Git references
 
 Resolve values from `cwd` git data.
@@ -214,6 +378,41 @@ gitTimestampAbsolutePath: ${git:timestamp('package.json')}
 ```
 <!-- end-doc-gen -->
 
+
+### Cron Values
+
+Convert human-readable time expressions into cron expressions. Supports single quotes for values.
+
+```yml
+# Basic patterns
+everyMinute: ${cron('every minute')}        # * * * * *
+everyHour: ${cron('every hour')}            # 0 * * * *
+everyDay: ${cron('every day')}              # 0 0 * * *
+weekdays: ${cron('weekdays')}               # 0 0 * * 1-5
+midnight: ${cron('midnight')}               # 0 0 * * *
+noon: ${cron('noon')}                       # 0 12 * * *
+
+# Interval patterns
+every5Minutes: ${cron('every 5 minutes')}   # */5 * * * *
+every15Minutes: ${cron('every 15 minutes')} # */15 * * * *
+every2Hours: ${cron('every 2 hours')}       # 0 */2 * * *
+every3Days: ${cron('every 3 days')}         # 0 0 */3 * * *
+
+# Specific times
+at930: ${cron('at 9:30')}                   # 30 9 * * *
+at930pm: ${cron('at 9:30 pm')}              # 30 21 * * *
+at1200: ${cron('at 12:00')}                 # 0 12 * * *
+at1230am: ${cron('at 12:30 am')}            # 30 0 * * *
+
+# Weekday patterns
+mondayMorning: ${cron('on monday at 9:00')}  # 0 9 * * 1
+fridayEvening: ${cron('on friday at 17:00')} # 0 17 * * 5
+sundayNoon: ${cron('on sunday at 12:00')}    # 0 12 * * 0
+
+# Pre-existing cron expressions
+customCron: ${cron('15 2 * * *')}           # 15 2 * * *
+```
+
 ### Filters (experimental)
 
 Filters will transform the resolved variables

package/cli.js

@@ -9,10 +9,10 @@ const { logHeader } = require('./src/utils/logs')
 // Parse command line arguments
 const argv = minimist(process.argv.slice(2), {
   string: ['output', 'o', 'format', 'f'],
-  boolean: ['help', 'h', 'version', 'v', 'debug', 'allow-unknown', 'allow-undefined', 'list', 'info'],
+  boolean: ['help', 'h', 'version', 'v', 'debug', 'allow-unknown', 'allow-undefined', 'list', 'info', 'verify'],
   alias: {
     h: 'help',
-    v: 'version',
+    v: 'verify',
     o: 'output',
     f: 'format',
     l: 'list',
@@ -38,6 +38,7 @@ Options:
   -f, --format <format>     Output format: json, yaml, or js (default: json)
   -d, --debug               Enable debug mode
   -i, --info                Show info about the config
+  -v, --verify              Verify the config
   --allow-unknown           Allow unknown variables to pass through
   --allow-undefined         Allow undefined values in the final output
 
@@ -85,7 +86,8 @@ if (options.dynamicArgs.verbose) {
   const { 
     _, 
     verbose, 
-    v, 
+    v,
+    verify,
     debug, 
     d, 
     help, 
@@ -111,6 +113,11 @@ if (options.dynamicArgs.verbose) {
   console.log()
 }
 
+let isSetupMode = false
+if (argv._.length) {
+  isSetupMode = argv._.includes('setup')
+}
+
 // Create Configorama instance
 const configorama = new Configorama(inputFile, options)
 // console.log('configorama', configorama)

package/index.d.ts

@@ -0,0 +1,45 @@
+// Type definitions for configorama
+// Project: https://github.com/DavidWells/configorama
+// Definitions by: Claude AI
+
+// Export the 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>
+
+// 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
+  }
+): Promise<T>
+
+export function sync<T>(
+  configPath: string,
+  options?: {
+    options?: Record<string, any>
+    variableSources?: Record<string, any>
+    [key: string]: any
+  }
+): T

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "configorama",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Variable support for configuration files",
   "main": "src/index.js",
+  "types": "index.d.ts",
   "files": [
     "cli.js",
     "src",
+    "index.d.ts",
     "package.json",
     "package-lock.json",
     "README.md"
@@ -16,6 +18,7 @@
   },
   "scripts": {
     "docs": "node ./scripts/docs.js",
+    "t": "./scripts/run-tests.sh",
     "test": "npm run test:lib && uvu tests \".*\\.test.js$\" ",
     "test:tests": "uvu tests \".*\\.test.js$\" ",
     "test:api": "uvu tests/api api.test.js",
@@ -34,12 +37,15 @@
     "url": "https://github.com/DavidWells/configorama"
   },
   "dependencies": {
-    "@davidwells/box-logger": "^1.0.10",
+    "@davidwells/box-logger": "^1.0.20",
     "@iarna/toml": "^2.2.5",
+    "alias-hq": "^6.2.3",
     "dot-prop": "^5.3.0",
-    "env-stage-loader": "^1.1.1",
+    "env-stage-loader": "^1.1.3",
     "find-up": "^3.0.0",
     "git-url-parse": "^14.0.0",
+    "ini": "^5.0.0",
+    "jiti": "^2.4.2",
     "js-yaml": "^3.14.1",
     "json5": "^2.2.3",
     "lodash.assign": "^4.2.0",
@@ -63,11 +69,14 @@
     "minimist": "^1.2.8",
     "promise.prototype.finally": "^3.1.8",
     "safe-chalk": "^1.0.0",
+    "subscript": "^9.1.0",
     "sync-rpc": "^1.3.6",
     "traverse": "^0.6.8"
   },
   "devDependencies": {
     "markdown-magic": "^3.4.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.8.3",
     "uvu": "^0.5.6",
     "watchlist": "^0.3.1"
   }

package/src/index.js

@@ -1,17 +1,20 @@
 const Configorama = require('./main')
 const parsers = require('./parsers')
-const forceSync = require('sync-rpc')
 
 module.exports.Configorama = Configorama
 
 /**
  * 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] 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.
  * @return {Promise} resolved configuration
  */
@@ -23,12 +26,18 @@ module.exports = async (configPathOrObject, settings = {}) => {
 }
 
 module.exports.sync = (configPathOrObject, settings = {}) => {
-  if (settings.dynamicArgs && typeof settings.dynamicArgs === 'function') {
+  const _settings = settings || {}
+  if (_settings.dynamicArgs && typeof _settings.dynamicArgs === 'function') {
     throw new Error('Dynamic args must be serializable value for sync usage. Use Async instead')
   }
-  return forceSync(require.resolve('./sync'), settings.variableSources)({
+  if (!_settings.options) {
+    const cliArgs = require('minimist')(process.argv.slice(2))
+    _settings.options = cliArgs
+  }
+  const forceSync = require('sync-rpc')
+  return forceSync(require.resolve('./sync'), _settings.variableSources)({
     filePath: configPathOrObject,
-    settings: settings
+    settings: _settings
   })
 }