API

config.load(options?)

Loads .env and xpulse.json, merges defaults and resolves ${VAR}. Emits config:loaded after successful load.

1 await config.load();
2 await config.load({ path: '/app', env: 'stage' });

Option	Type	Description
`path`	`string`	Directory containing `xpulse.json` – default: `process.cwd()`
`env`	`string`	Environment for `.env.{env}` – fallback: `process.env.NODE_ENV`

Errors:

Situation	Behaviour
`xpulse.json` not found	throws `Error`
Invalid JSON	throws `Error`
`name` missing	throws `Error`
Unknown keys	ignored, no warning
`${VAR}` unresolvable	warning, value stays `${VAR}`

config.get(path, fallback?)

Returns a value from the configuration. Supports dot notation.

1 config.get('http.port')              // '3000'
2 config.get('i18n.locales')           // ['de', 'en']
3 config.get('sources.chat.url')       // 'https://chat.xpulse.one'
4 config.get('release.current')        // '1.3.0' (custom key)
5 config.get('missing.key', 'default') // 'default'
6 config.get('missing.key')            // null

Parameter	Type	Description
`path`	`string`	Dot-notation path
`fallback`	`unknown`	Returned if path does not exist (default: `null`)

config.all()

Returns all configuration values – including defaults and resolved ${VAR}. Returns a copy, not a reference.

1 const all = config.all();
2 // → { name: 'xpulse-web', type: 'tool', http: { port: '3000' }, ... }

config.name

Shorthand for config.get('name').

1 config.name  // 'xpulse-web'

config.type

Shorthand for config.get('type').

1 config.type  // 'tool'

config.loaded

true after a successful load().

1 config.loaded  // true | false

Event: `config:loaded`

Emitted after load().

1 // Payload:
2 {
3     name:  'xpulse-web',
4     type:  'tool',
5     env:   'production',         // process.env.NODE_ENV | null
6     files: [
7         '/app/xpulse.json',
8         '/app/.env',
9         '/app/.env.production',  // only if present
10     ]
11 }

1	await config.load();
2	await config.load({ path: '/app', env: 'stage' });

1	config.get('http.port') // '3000'
2	config.get('i18n.locales') // ['de', 'en']
3	config.get('sources.chat.url') // 'https://chat.xpulse.one'
4	config.get('release.current') // '1.3.0' (custom key)
5	config.get('missing.key', 'default') // 'default'
6	config.get('missing.key') // null

1	const all = config.all();
2	// → { name: 'xpulse-web', type: 'tool', http: { port: '3000' }, ... }

1	// Payload:
2	{
3	name: 'xpulse-web',
4	type: 'tool',
5	env: 'production', // process.env.NODE_ENV \| null
6	files: [
7	'/app/xpulse.json',
8	'/app/.env',
9	'/app/.env.production', // only if present
10	]
11	}