Config

Multi-source configuration management with deep merge, dot-path access, env loading, and validation

Package: @robinpath/config | Category: Other | Type: Utility

Authentication

No authentication required. All functions are available immediately.

Use Cases

Use the config module when you need to:

• Create config with defaults -- Use config.create to perform this operation
• Load config from file (.json, .env) -- Use config.load to perform this operation
• Load from environment variables -- Use config.loadEnv to perform this operation
• Get config value by dot path -- Use config.get to perform this operation
• Get entire config -- Use config.getAll to perform this operation

Quick Reference

Function	Description	Returns
create	Create config with defaults	Config object
load	Load config from file (.json, .env)	Merged config
loadEnv	Load from environment variables	Merged config
get	Get config value by dot path	Config value
set	Set config value by dot path	true
getAll	Get entire config	Full config
merge	Deep merge into config	Merged config
has	Check if path exists	true if exists
remove	Remove config key	true if removed
clear	Clear entire config	true
list	List all config names	Config names
validate	Validate required keys exist	{valid, missing}
freeze	Freeze config (immutable)	true
toEnv	Convert config to env format	Env-format string

Functions

create

Create config with defaults

Module: config | Returns: object -- Config object

config.create "app" {"port": 3000, "debug": false}

Parameter	Type	Required	Description
name	string	No	Config name
defaults	object	No	Default values

---

load

Load config from file (.json, .env)

Module: config | Returns: object -- Merged config

config.load "./config.json"

Parameter	Type	Required	Description
filePath	string	Yes	Config file path
name	string	No	Config name

---

loadEnv

Load from environment variables

Module: config | Returns: object -- Merged config

config.loadEnv "APP_"

Parameter	Type	Required	Description
prefix	string	No	Env var prefix filter
name	string	No	Config name

---

get

Get config value by dot path

Module: config | Returns: any -- Config value

config.get "database.host" "localhost"

Parameter	Type	Required	Description
path	string	Yes	Dot-separated path
default	any	No	Default value
name	string	No	Config name

---

set

Set config value by dot path

Module: config | Returns: boolean -- true

config.set "database.port" 5432

Parameter	Type	Required	Description
path	string	Yes	Dot-separated path
value	any	Yes	Value
name	string	No	Config name

---

getAll

Get entire config

Module: config | Returns: object -- Full config

config.getAll

Parameter	Type	Required	Description
name	string	No	Config name

---

merge

Deep merge into config

Module: config | Returns: object -- Merged config

config.merge {"database": {"port": 5432}}

Parameter	Type	Required	Description
data	object	Yes	Data to merge
name	string	No	Config name

---

has

Check if path exists

Module: config | Returns: boolean -- true if exists

config.has "database.host"

Parameter	Type	Required	Description
path	string	Yes	Dot-separated path
name	string	No	Config name

---

remove

Remove config key

Module: config | Returns: boolean -- true if removed

config.remove "debug"

Parameter	Type	Required	Description
path	string	Yes	Dot-separated path
name	string	No	Config name

---

clear

Clear entire config

Module: config | Returns: boolean -- true

config.clear

Parameter	Type	Required	Description
name	string	No	Config name

---

list

List all config names

Module: config | Returns: array -- Config names

config.list

Parameter	Type	Required	Description
(none)		No	Call with no arguments

---

validate

Validate required keys exist

Module: config | Returns: object -- {valid, missing}

config.validate ["database.host", "database.port"]

Parameter	Type	Required	Description
required	array	Yes	Required dot paths
name	string	No	Config name

---

freeze

Freeze config (immutable)

Module: config | Returns: boolean -- true

config.freeze

Parameter	Type	Required	Description
name	string	No	Config name

---

toEnv

Convert config to env format

Module: config | Returns: string -- Env-format string

config.toEnv "app" "APP_"

Parameter	Type	Required	Description
name	string	No	Config name
prefix	string	No	Key prefix

---

Error Handling

All functions throw on failure. Common errors:

Error	Cause
(standard errors)	Check function parameters and authentication

@desc "Create and validate result"
do
  set $result as config.create "app" {"port": 3000, "debug": false}
  if $result != null
    print "Success"
  else
    print "No result"
  end
enddo

Recipes

1. List and iterate

Retrieve all items and loop through them.

@desc "Get and iterate results"
do
  set $result as config.get "database.host" "localhost"
  each $item in $result
    print $item
  end
enddo

2. Create a new item with create

Create a new resource and capture the result.

set $result as config.create "app" {"port": 3000, "debug": false}
print "Created: " + $result

3. Check before creating

List existing items and only create if needed.

@desc "Get and create"
do
  set $existing as config.get "database.host" "localhost"
  if $existing == null
    config.create "app" {"port": 3000, "debug": false}
    print "Item created"
  else
    print "Item already exists"
  end
enddo

4. Multi-step Config workflow

Chain multiple config operations together.

@desc "Create, load, and more"
do
  set $r_create as config.create "app" {"port": 3000, "debug": false}
  set $r_load as config.load "./config.json"
  set $r_loadEnv as config.loadEnv "APP_"
  print "All operations complete"
enddo

5. Safe create with validation

Check results before proceeding.

@desc "Create and validate result"
do
  set $result as config.create "app" {"port": 3000, "debug": false}
  if $result != null
    print "Success: " + $result
  else
    print "Operation returned no data"
  end
enddo

Related Modules

• json -- JSON module for complementary functionality