Stone.js - Config

Fluent and type-safe configuration management with deep property access, merging, and dynamic proxy fallback.

---

Overview

@stone-js/config provides a smart, fluent API to manage application settings in any JavaScript or TypeScript project.

• Deep property access (config.get('nested.key'))
• Automatic fallback via Proxy (config.someKey)
• Merge strategies for objects and arrays
• Default value support, get('name', 'fallback')
• Fully tested with 100% coverage

Installation

Install using your preferred package manager:

npm i @stone-js/config
# or
yarn add @stone-js/config
# or
pnpm add @stone-js/config

[!IMPORTANT] This package is pure ESM. Ensure your package.json includes "type": "module" or configure your bundler appropriately.

import { Config } from '@stone-js/config'

Getting Started

Create a Config instance

const config = Config.create({
  app: { name: 'MyApp', env: 'prod' },
  features: { darkMode: true }
})

Or from JSON:

const config = Config.fromJson('{ "enabled": true }')

Core API

Access values

config.get('app.name') // 'MyApp'
config.get('missing.key') // undefined
config.get('missing.key', 'default') // 'default'

Proxy fallback also works:

config['app.env'] // 'prod'

Check existence

config.has('features.darkMode') // true

First match

config.firstMatch(['missing', 'features.darkMode']) // true
config.firstMatch(['none'], 'fallback') // 'fallback'

Retrieve many keys

config.getMany(['app.name', 'features.darkMode'])
// { 'app.name': 'MyApp', 'features.darkMode': true }

config.getMany({ 'unknown': 'default' })
// { unknown: 'default' }

Set values

config.set('app.name', 'NewApp')
config.set({ 'app.env': 'dev', 'features.debug': true })

Merge with add()

config.add('features', { beta: false })
// merges into existing `features` object

config.add('list', [1])
config.add('list', 2)
// appends to array if already exists

Set only if not exists

config.setIf('features.darkMode', false) // won't overwrite
config.setIf('newKey', 123) // will set

Check exact value

config.is('app.env', 'prod') // true or false

Replace or reset all

config.setItems({ reset: true })
config.clear() // clears everything

Export

config.all() // returns raw object
config.toJson() // returns stringified version

Full Example

const config = Config.create({ count: 1, nested: { flag: true } })

config.set('nested.flag', false)
config.add('nested', { added: 42 })
config.setIf('newKey', 'set only once')

console.log(config.get('nested.flag')) // false
console.log(config.get('nested.added')) // 42
console.log(config.get('newKey')) // 'set only once'

console.log(config.toJson()) // '{"count":1,"nested":{"flag":false,"added":42},"newKey":"set only once"}'

Why use @stone-js/config?

• Fully tested (100% test coverage)
• Deep access, merging, and proxy support
• Can replace many ad-hoc config patterns
• Clean design with extensibility in mind
• TypeScript-first

Summary

@stone-js/config is a powerful, type-safe configuration library that simplifies managing application settings. With its fluent API, deep property access, and dynamic proxy fallback, it provides a robust solution for any JavaScript or TypeScript project.

Learn More

This package is part of the Stone.js ecosystem, a modern JavaScript framework built around the Continuum Architecture.

Explore the full documentation: https://stonejs.dev

API documentation

• API

Contributing

See CONTRIBUTING.md

Credits

• Lodash for deep utilities
• Inspired by Laravel Config