| # RC9 |
|
|
| <!-- automd:badges color=yellow codecov bundlejs --> |
|
|
| [](https://npmjs.com/package/rc9) |
| [](https://npmjs.com/package/rc9) |
| [](https://bundlejs.com/?q=rc9) |
| [](https://codecov.io/gh/unjs/rc9) |
|
|
| <!-- /automd --> |
|
|
| Read/Write RC configs couldn't be easier! |
|
|
| ## Install |
|
|
| Install dependencies: |
|
|
| <!-- automd:pm-i --> |
|
|
| ```sh |
| # ✨ Auto-detect |
| npx nypm install rc9 |
| |
| # npm |
| npm install rc9 |
| |
| # yarn |
| yarn add rc9 |
| |
| # pnpm |
| pnpm install rc9 |
| |
| # bun |
| bun install rc9 |
| ``` |
|
|
| <!-- /automd --> |
|
|
| Import utils: |
|
|
| <!-- automd:jsimport cjs src="./src/index.ts"--> |
|
|
| **ESM** (Node.js, Bun) |
|
|
| ```js |
| import { |
| defaults, |
| parse, |
| parseFile, |
| read, |
| readUser, |
| serialize, |
| write, |
| writeUser, |
| update, |
| updateUser, |
| } from "rc9"; |
| ``` |
|
|
| **CommonJS** (Legacy Node.js) |
|
|
| ```js |
| const { |
| defaults, |
| parse, |
| parseFile, |
| read, |
| readUser, |
| serialize, |
| write, |
| writeUser, |
| update, |
| updateUser, |
| } = require("rc9"); |
| ``` |
|
|
| <!-- /automd --> |
|
|
|
|
| ## Usage |
|
|
| `.conf`: |
|
|
| ```ini |
| db.username=username |
| db.password=multi word password |
| db.enabled=true |
| ``` |
|
|
| **Update config:** |
|
|
| ```ts |
| update({ 'db.enabled': false }) // or update(..., { name: '.conf' }) |
| ``` |
|
|
| Push to an array: |
|
|
| ```ts |
| update({ 'modules[]': 'test' }) |
| ``` |
|
|
| **Read/Write config:** |
|
|
| ```ts |
| const config = read() // or read('.conf') |
| |
| // config = { |
| // db: { |
| // username: 'username', |
| // password: 'multi word password', |
| // enabled: true |
| // } |
| // } |
| |
| config.enabled = false |
| write(config) // or write(config, '.conf') |
| ``` |
|
|
| **User Config:** |
|
|
| It is common to keep config in user home directory (MacOS: `/Users/{name}`, Linux: `/home/{name}`, Windows: `C:\users\{name}`) |
|
|
| you can use `readUser`/`writeuser`/`updateUser` shortcuts to quickly do this: |
|
|
| ```js |
| writeUser({ token: 123 }, '.zoorc') // Will be saved in {home}/.zoorc |
| |
| const conf = readUser('.zoorc') // { token: 123 } |
| ``` |
|
|
| ## Unflatten |
|
|
| RC uses [flat](https://www.npmjs.com/package/flat) to automatically flat/unflat when writing and reading rcfile. |
|
|
| It means that you can use `.` for keys to define objects. Some examples: |
|
|
| - `hello.world = true` <=> `{ hello: { world: true }` |
| - `test.0 = A` <=> `tags: [ 'A' ]` |
|
|
| **Note:** If you use keys that can override like `x=` and `x.y=`, you can disable this feature by passing `flat: true` option. |
|
|
| **Tip:** You can use keys ending with `[]` to push to an array like `test[]=A` |
|
|
| ## Native Values |
|
|
| RC uses [destr](https://www.npmjs.com/package/destr) to convert values into native javascript values. |
|
|
| So reading `count=123` results `{ count: 123 }` (instead of `{ count: "123" }`) if you want to preserve strings as is, can use `count="123"`. |
|
|
| ## Exports |
|
|
| ```ts |
| const defaults: RCOptions; |
| function parse(contents: string, options?: RCOptions): RC |
| function parseFile(path: string, options?: RCOptions): RC |
| function read(options?: RCOptions | string): RC; |
| function readUser(options?: RCOptions | string): RC; |
| function serialize(config: RC): string; |
| function write(config: RC, options?: RCOptions | string): void; |
| function writeUser(config: RC, options?: RCOptions | string): void; |
| function update(config: RC, options?: RCOptions | string): RC; |
| function updateUser(config: RC, options?: RCOptions | string): RC; |
| ``` |
|
|
| **Types:** |
|
|
| ```ts |
| type RC = Record<string, any>; |
| interface RCOptions { |
| name?: string; |
| dir?: string; |
| flat?: boolean; |
| } |
| ``` |
|
|
| **Defaults:** |
|
|
| ```ini |
| { |
| name: '.conf', |
| dir: process.cwd(), |
| flat: false |
| } |
| ``` |
|
|
| ### Why RC9? |
|
|
| Be the first one to guess 🐇 <!-- Hint: do research about rc files history --> |
|
|
| ## License |
|
|
| <!-- automd:contributors license=MIT --> |
|
|
| Published under the [MIT](https://github.com/unjs/rc9/blob/main/LICENSE) license. |
| Made by [community](https://github.com/unjs/rc9/graphs/contributors) 💛 |
| <br><br> |
| <a href="https://github.com/unjs/rc9/graphs/contributors"> |
| <img src="https://contrib.rocks/image?repo=unjs/rc9" /> |
| </a> |
|
|
| <!-- /automd --> |
|
|
