https://github.com/elmccd/ceed
Set of JS async utils making building pipelines in JS easier
https://github.com/elmccd/ceed
async-await build-pipelines build-tool ci-cd pipelines
Last synced: about 1 month ago
JSON representation
Set of JS async utils making building pipelines in JS easier
- Host: GitHub
- URL: https://github.com/elmccd/ceed
- Owner: elmccd
- License: mit
- Created: 2017-02-18T21:35:59.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2017-02-19T18:36:22.000Z (about 8 years ago)
- Last Synced: 2025-03-11T19:47:59.968Z (about 2 months ago)
- Topics: async-await, build-pipelines, build-tool, ci-cd, pipelines
- Language: JavaScript
- Homepage:
- Size: 14.6 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: license
Awesome Lists containing this project
README
# ceed [](https://travis-ci.org/elmccd/ceed)
> Set of JS async utils making building pipelines in JS easier
Library is taking advantage of ES2017 `async/await` functionality to
allow creating more readable scripts performing command operations.
## In short
```js
const maybe = require('ceed').maybe;
const ls = await maybe('ls build')
console.log(ls);
/*
{
"code": 0,
"error": null,
"failed": false,
"succeed": true,
"output": "another.c\nfile.txt\n",
"value": "another.c\nfile.txt",
"values": [
"another.c",
"file.txt"
],
"stderr": ""
} */
```
## Install
```
$ npm install --save ceed
```
## Running
You need node 6+ with the `--harmony` flag or installed [babel-cli](https://github.com/babel/babel/tree/master/packages/babel-cli)
`node --harmony app.js`
or
`./node_modules/.bin/babel-node app.js`
## Example app.js
```js
const {
run,
commit,
maybe
} = require('ceed');
(async function () {
await commit('mkdir -p build', {}, {verbose: true});
const build = await maybe('bash ./script.sh -o build');
if (build.failed) {
//handle fail
console.log('Failed with: ' + build.code);
}
const builtItems = await run('ls', {
cwd: 'build'
}).catch(err => {
//handle run promise rejection
});
buildItems.values.forEach(file => {
console.log(`${file} built successfully`);
});
})();
```
## API
Package exports three methods that share the same API with different
way of handling errors.
- `ceed.run(command: string, [execOptions]: Object, [ceedOptions]: {verbose: false})`
- `ceed.maybe(command: string, [execOptions]: Object, [ceedOptions]: {verbose: false})`
- `ceed.commit(command: string, [execOptions]: Object, [ceedOptions]: {verbose: false})`
See [node.js child_process.exec options](https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback)
for all `execOptions`
Example:
```js
await maybe('ls', {cwd: 'build'})
```
**ceedOptions**:
- `verbose: boolean` - output result of every command. Default `false`.
You can set verbose option globally by setting env variable `CEED_VERBOSE` to true.
#### `ceed.run`
`Run` is a basic method which wraps `child_process.exec` into Promise
interface.
You can catch failed commands using Promise `.catch(fn)` syntax.
#### `ceed.maybe`
`Maybe` works like run, except when the command fails Promise is still
resolved successfully. You can get script exit code and status checking
`.succeed`, `.failed` or `.code` property in resolved object.
#### `ceed.commit`
`Commit` works like run, except on fail it throws an error instead of rejecting
the promise and it outputs more failure details
### Resolved/Rejected object structure
```js
{
code: number | string, //script return code
error: Error, //.exec failure error object
failed: boolean, //is .code different than 0
succeed: boolean, //oposite of failed
output: string, //value of stdout
value: string, //trimmed .output, useuful for single value outputs
values: Array, //trimmed .output splitted by lines
stderr: string // value of stderr
}
```
## License
MIT © [Maciej Dudzinski](http://github.com/elmccd)