https://github.com/stone-foundation/stone-js-config
Fluent and simple API with string deep dot access to manage configurations in any JavaScript/TypeScript project
https://github.com/stone-foundation/stone-js-config
context-aware continuum-architecture javascript official-stonejs stone-foundation stonejs stonejs-blueprint stonejs-core typescript
Last synced: 3 months ago
JSON representation
Fluent and simple API with string deep dot access to manage configurations in any JavaScript/TypeScript project
- Host: GitHub
- URL: https://github.com/stone-foundation/stone-js-config
- Owner: stone-foundation
- License: mit
- Created: 2023-09-25T13:32:38.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-06-12T02:52:13.000Z (about 1 year ago)
- Last Synced: 2025-06-12T03:40:00.168Z (about 1 year ago)
- Topics: context-aware, continuum-architecture, javascript, official-stonejs, stone-foundation, stonejs, stonejs-blueprint, stonejs-core, typescript
- Language: TypeScript
- Homepage: https://stonejs.dev
- Size: 200 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# Stone.js - Config
[](https://opensource.org/licenses/MIT)
[](https://www.npmjs.com/package/@stone-js/config)
[](https://www.npmjs.com/package/@stone-js/config)
[](https://github.com/stone-foundation/stone-js-config/actions/workflows/main.yml)
[](https://github.com/stone-foundation/stone-js-config/actions/workflows/release.yml)
[](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-config)
[](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-config)
[](./SECURITY.md)
[](https://github.com/stone-foundation/stone-js-config/security/code-scanning)
[](https://github.com/stone-foundation/stone-js-config/network/updates)
[](https://conventionalcommits.org)
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:
```bash
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.
```ts
import { Config } from '@stone-js/config'
```
## Getting Started
### Create a Config instance
```ts
const config = Config.create({
app: { name: 'MyApp', env: 'prod' },
features: { darkMode: true }
})
```
Or from JSON:
```ts
const config = Config.fromJson('{ "enabled": true }')
```
## Core API
### Access values
```ts
config.get('app.name') // 'MyApp'
config.get('missing.key') // undefined
config.get('missing.key', 'default') // 'default'
```
Proxy fallback also works:
```ts
config['app.env'] // 'prod'
```
### Check existence
```ts
config.has('features.darkMode') // true
```
### First match
```ts
config.firstMatch(['missing', 'features.darkMode']) // true
config.firstMatch(['none'], 'fallback') // 'fallback'
```
### Retrieve many keys
```ts
config.getMany(['app.name', 'features.darkMode'])
// { 'app.name': 'MyApp', 'features.darkMode': true }
config.getMany({ 'unknown': 'default' })
// { unknown: 'default' }
```
### Set values
```ts
config.set('app.name', 'NewApp')
config.set({ 'app.env': 'dev', 'features.debug': true })
```
### Merge with `add()`
```ts
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
```ts
config.setIf('features.darkMode', false) // won't overwrite
config.setIf('newKey', 123) // will set
```
### Check exact value
```ts
config.is('app.env', 'prod') // true or false
```
### Replace or reset all
```ts
config.setItems({ reset: true })
config.clear() // clears everything
```
### Export
```ts
config.all() // returns raw object
config.toJson() // returns stringified version
```
## Full Example
```ts
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](https://stonejs.dev)
## API documentation
* [API](https://github.com/stone-foundation/stone-js-config/blob/main/docs)
## Contributing
See [CONTRIBUTING.md](https://github.com/stone-foundation/stone-js-config/blob/main/CONTRIBUTING.md)
## Credits
* [Lodash](https://github.com/lodash/lodash) for deep utilities
* Inspired by [Laravel Config](https://github.com/laravel/framework/blob/10.x/src/Illuminate/Config/Repository.php)