# @microbs.io/core
> microservices observability
Latest version **0.2.9** (published 2023-06-16) · Apache-2.0 license · 0 weekly downloads
## Install
```sh
npm install @microbs.io/core
pnpm add @microbs.io/core
yarn add @microbs.io/core
bun add @microbs.io/core
```
## Health
**Score 15/100 (F)** — status: abandoned.
Positive: no vulnerabilities.
Warnings: low downloads; no types; no esm support; pre 1.0.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 0.2.9 |
| Published | 2023-06-16 |
| First published | 2022-04-28 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=14.16.1 |
| Dependencies | 5 |
| Unpacked size | 64.3 KB |
| Known vulnerabilities | 0 (+23 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 0 |
| Maintainers | microbs.io |
| Keywords | microbs |
## Links
- npm: https://www.npmjs.com/package/@microbs.io/core
- Repository: https://github.com/microbs-io/microbs-core
- Homepage: https://github.com/microbs-io/microbs-core#readme
- Issues: https://github.com/microbs-io/microbs-core/issues
- npm.io page: https://npm.io/package/@microbs.io/core
## Dependencies (5)
- [axios](https://npm.io/package/axios.md) ^0.21.1
- [chalk](https://npm.io/package/chalk.md) ^4.1.1
- [lodash](https://npm.io/package/lodash.md) ^4.17.21
- [js-yaml](https://npm.io/package/js-yaml.md) ^4.1.0
- [shell-quote](https://npm.io/package/shell-quote.md) ^1.7.3
## Recent versions
- 0.2.9 (latest) — 2023-06-16
- 0.2.8 — 2022-11-14
- 0.2.7 — 2022-09-19
- 0.2.6 — 2022-08-30
- 0.2.5 — 2022-08-30
- 0.2.4 — 2022-05-16
- 0.2.3 — 2022-05-16
- 0.2.2 — 2022-05-16
- 0.2.1 — 2022-05-13
- 0.2.0 — 2022-05-13
- 0.1.19-alpha — 2022-05-12
- 0.1.18-alpha — 2022-05-12
- 0.1.17-alpha — 2022-05-12
- 0.1.16-alpha — 2022-05-12
- 0.1.15-alpha — 2022-05-12
- … 15 more at https://npm.io/package/@microbs.io/core/versions
## README
[](https://github.com/microbs-io/microbs-core/actions)
[](https://www.npmjs.com/package/@microbs.io/core)
# microbs-core
`@microbs.io/core` is a common library used by [`microbs-cli`](https://github.com/microbs-io/microbs-cli)
and microbs plugins. Contributors should use `@microbs.io/core` for things such
as logging, configuration management, command execution, and HTTP requests to
ensure a consistent experience in microbs.
## Usage
You can import all the core modules as follows:
```js
const { config, context, logger, rollout, state, utils } = require('@microbs.io/core')
```
Or you can limit your imports only to the modules you need. For example, if you
only need access to `config` and `logger`, then you can use:
```js
const { config, logger } = require('@microbs.io/core')
```
## Reference
* [`config`](#config)
* [`context`](#context)
* [`logger`](#logger)
* [`rollout`](#rollout)
* [`state`](#state)
* [`utils`](#utils)
### `config`
`config` provides a read-only interface to the microbs configuration file
(`config.yaml`) and stores its values in memory as a read-only object.
#### `config.load(filepath?: string)`
Load, parse, and persist in memory the microbs config file, which is located by
`filepath`. By default, `filepath` is `$CWD/config.yaml`, where `$CWD` is the
current directory of the user running the microbs CLI. If the file doesn't exist,
then the default `filepath` is `$HOME/.microbs/config.yaml`. Usually plugins
don't need to run `config.load()` except during tests, because the microbs CLI
will load the config file before it loads the plugins and store the filepath at
`context.get('path.config')`.
#### `config.get(path?: string)`
Get a value from the config object by its key path in the object. Because the
config file can be nested, you can retrieve the values of nested keys by using
dot notation. For example, given the following configuration in config.yaml...
```yaml
deployment:
plugins:
observability: grafana-cloud
```
...you can use `config.get('deployment.plugins.observability')` to retrieve the
value of the observability plugin, which the function would return as
`'grafana-cloud'`.
### `context`
`context` provides information about the microbs execution environment. Values
can be added to the context object, but they cannot be removed or changed once
they are added.
The microbs CLI sets the following context variables:
* `command` - The command that the user ran from the microbs CLI (e.g. `setup`)
* `args` - The arguments that the user supplied with `command` (e.g. `--kubernetes --log-level debug`)
* `path.cli` - Absolute path to the directory of the microbs CLI
* `path.user` - Absolute path to the current working directory of the user running the microbs CLI
* `path.config` - Absolute path to the config file (`config.yaml`) used to store deployment inputs
* `path.state` - Absolute path to the state file (`state.yaml`) used to store post-deployment details
* `path.env` - Absolute path to the .env file (`.env`) used by `microbs-secrets`
* `path.app` - Absolute path to the installation directory of the application named in `deployment.app`
* `path.plugin.kubernetes` - Absolute path to the installation directory of the plugin in `deployment.plugins.kubernetes`
* `path.plugin.observability` - Absolute path to the installation directory of the plugin in `deployment.plugins.observability`
* `path.plugin.alerts` - Absolute path to the installation directory of the plugin in `deployment.plugins.alerts`
#### `context.get(key?: string)`
Get a value from the context object by its key path in the object. You can
retrieve the values of nested keys by using dot notation just like in
[`config.get()`](#config.get).
#### `context.set(key?: string)`
Set a value in the context object by its key path in the object. You can set
the values of nested keys by using dot notation just like in
[`config.get()`](#config.get).
### `logger`
`logger` provides a standardized logger that can serialize objects, colorize
outputs based on log levels, display verbose metadata, and filter outputs by
log levels. Objects are serialized to JSON.
#### `logger.debug(message: any)`
Write a log message that will appear only when `--log-level` is set to a value
that is greater than or equal to `debug`.
#### `logger.info(message: any)`
Write a log message that will appear only when `--log-level` is set to a value
that is greater than or equal to `info`.
#### `logger.warn(message: any)`
Write a log message that will appear only when `--log-level` is set to a value
that is greater than or equal to `warn`.
#### `logger.error(message: any)`
Write a log message that will appear only when `--log-level` is set to a value
that is equal to `error`.
### `rollout`
`rollout` rolls out a skaffold profile to the deployed Kubernetes cluster.
#### rollout.run(opts: object)
Roll out a skaffold profile to the deployed Kubernetes cluster.
What happens when this function is called:
1. `microbs-secrets` is deleted (using `kubectl delete secret`)
2. The state file is saved and overwritten (using [`state.save()`](#state.save))
3. The .env file is saved and overwritten (using [`utils.objToEnv()`](@utils.objToEnv))
4. `microbs-secrets` is deployed using the new .env file (using `kubectl create secret`)
5. The skaffold profile is deployed with `skaffold run`
`rollout.run()` can be controlled with an `opts` object:
* `opts.action` - Can be `"run"` or `"delete"` to invoke either `skaffold run` or `skaffold delete` (Default: `"run"`)
* `opts.profile` - Which skaffold profile to invoke from `skaffold.yaml` (Default: `"main"`)
* `opts.skaffoldFilepath` - Path to the `skaffold.yaml` file to use (Default: )
### `state`
`state` provides a read-write interface to the microbs state file (`state.yaml`)
and stores its values in memory as a read-write object.
#### `state.load(filepath?: string)`
Load, parse, and persist in memory the microbs state file, which is located by
`filepath`. By default, `filepath` is `$CWD/state.yaml`, where `$CWD` is the
current directory of the user running the microbs CLI. If the file doesn't exist,
then the default `filepath` is `$HOME/.microbs/confstateig.yaml`. Usually plugins
don't need to run `state.load()` except during tests, because the microbs CLI
will load the state file before it loads the plugins and store the filepath at
`context.get('path.state')`.
#### `state.get(path?: string)`
Get a value from the state object by its key path in the object. You can
retrieve the values of nested keys by using dot notation just like in
[`config.get()`](#config.get).
#### `state.set(path: string, value: string)`
Set a value from the state object by its key path in the object. You can
set the values of nested keys by using dot notation just like in
[`config.get()`](#config.get). Note that this will not persist to the state file
until you call [`state.save()`](#state.save)
#### `state.save(filepath: string)`
Save the entire contents of the state object to the state file, optionally
located by its `filepath`. Usually plugins don't need to set `filepath` except
during tests, because the microbs CLI will locate the state file and store the
filepath at `context.get('path.state')`.
### `utils`
`utils` provides commonly used functions to simplify the development of plugins
and help ensure consistent behavior across plugins. The most commonly used
functions for plugins include:
* [`utils.http()`](#utils.http) - Submit an HTTP request
* [`utils.exec()`](#utils.exec) - Execute a synchronous command.
* [`utils.sanitize()`](#utils.sanitize) - Escape an input for safe usage in [`utils.exec()`](#utils.exec)
* [`utils.loadFile()`](#utils.loadFile) - Load the contents of file
* [`utils.loadJson()`](#utils.loadJson) - Load and parse the contents of a JSON file
#### `utils.exec(command: string, hideStdout: boolean)`
Execute a synchronous command. The command will be logged if `--log-level` is
set to `debug`. Setting `hideStdout` to `true` lets you capture the contents
of `stdout` and `stderr`, which is recommended in most cases.
Returns a `result` object with the following properties:
* `result.code` - The exit code of the process
* `result.stdout` - The contents of stdout
* `result.stderr` - The contents of stderr if present
* `result.err` - The error object if an exception was thrown
Note: You should use [`utils.sanitize()`](#utils.sanitize) to escape potentially
unsafe characters from any inputs that you pass to the `command`. If your
`command` concatenates or interpolates other variables, those variables should
be escaped with [`utils.sanitize()`](#utils.sanitize).
Example usage:
```js
const { utils } = require('@microbs.io/core')
const result = utils.exec('echo "hello world"', true)
//result = { code: 0, stdout: 'hello world\n' }
```
#### `utils.expandvars(str: string, values: object)`
Given a string (`str`) substitute the environment variables with an object of
values (`values`).
Example usage:
```js
const { utils } = require('@microbs.io/core')
const result = utils.expandvars('FOO=${BAR}', { BAR: 'BAZ' })
// result = 'FOO=BAZ'
```
#### `utils.flatten(obj: object)`
Convert a nested object to a flattened object. This function is not intended to
be used directly by plugins, but it can be used to test and understand the
behavior of the function. The microbs CLI uses this function when creating the
`.env` file for `microbs-secrets`, normalizing the nested contents of the
`config.yaml` and `state.yaml` files into a flat structure used for `.env`.
Example usage:
```js
const { utils } = require('@microbs.io/core')
const output = utils.flatten({
'a': {
'b': {
'c.d': 'foo'
}
}
})
// output = { 'a.b.c.d': 'foo' }
```
#### `utils.http(opts?: object)` (async)
Submit an asynchronous HTTP request. `utils.http()` is a lightweight wrapper
around `axios.request()` that includes debugging logging for the request and
response when `--log-level` is set to `debug`.
Example usage:
```js
const { utils } = require('@microbs.io/core')
const result = await utils.http({
method: 'get',
url: 'https://microbs.io/'
})
```
#### `utils.loadFile(filepath: string)`
Read the contents of a file located by its `filepath`.
#### `utils.loadJson(filepath: string)`
Read and parse the contents of a JSON-formatted file located by its `filepath`.
#### `utils.loadTemplate(filepath: string, values: object)`
Read the contents of a file located by its `filepath` and substitute any
environment variables. [`utils.expandvars()`](#utils.expandvars) is what
performs the environment variable substitution.
#### `utils.loadTemplateJson(filepath: string, values: object)`
Read and parse the contents of a JSON-formatted file located by its `filepath`
and substitute any environment variables. [`utils.expandvars()`](#utils.expandvars)
is what performs the environment variable substitution.
#### `utils.objToEnv(obj: object)`
Serialize the contents of object to environment variable syntax suitable to be
saved as an `.env` file. Field names are flattened and uppercased, and dots are
replaced with underscores. This function is not intended to be used directly by
plugins, but it can be used to test and understand the behavior of the function.
Example usage:
```js
const { utils } = require('@microbs.io/core')
const output = utils.objToEnv({
foo: {
bar.baz: 'hello world'
}
})
// output = 'FOO_BAR_BAZ=hello world'
```
#### `utils.sanitize(value: string)`
Escape potentially unsafe characters in a string (`value`) so that the value can
be used safely as an input to [`utils.exec()`](#utils.exec).
Example usage:
```js
const { utils } = require('@microbs.io/core')
const output = utils.sanitize('foo;bar')
// output = 'foo\\;bar'
```
#### `utils.sleep(ms: number)`
Pause the execution of the current process by `ms` number of milliseconds.
Example usage:
```js
const { utils } = require('@microbs.io/core')
utils.sleep(1000) // Wait for 1 second
```
---
_Source: https://npm.io/package/@microbs.io/core · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._