checkscripts
Version:
Inspired by Dan Slimmon's concept of "Do Nothing scripts", this project facilitates incremental automation of repetitive tasks.
139 lines (103 loc) • 4.01 kB
Markdown
# Checkscripts
> Half checklist, half script. Incremental automation of repetitive tasks made easy.
## About
Inspired by [Dan Slimmon's idea of "Do-nothing scripting"](https://blog.danslimmon.com/2019/07/15/do-nothing-scripting-the-key-to-gradual-automation/), checkscripts allow you to programatically document a process. This gives the benefit of making the process easier to follow while allowing developers to incrementally automate it over time.
## Getting Started
Install `checkscripts` as an npm module:
```bash
npm install -s checkscripts
```
## Examples
### Running a Checkscript
```TypeScript
import { checkscript, step } from "checkscripts";
checkscript(
"Restore a database backup",
"This is our procedure for restoring a database backup."
)
.steps(
step(
"Retrieve the backup file",
"Log in to the [storage control panel](https://example.com/storage/) and download the latest backup file."
),
step(
"Load the backup data into the database",
"Run this command to load the backup data into the database: `psql < backup_YYYYMMDD.sql`."
),
step(
"Check the restored data for consistency",
"Log in to the database and make sure there are recent records in the events table."
),
)
.run();
```
Running this looks like:
<p align="center"><img src="/img/basic-demo.gif?raw=true"/></p>
Once a step has been automated, it can be turned into a function:
```TypeScript
import { checkscript, step } from "checkscripts";
interface ExampleContext {
backupFilePath: string | undefined;
}
checkscript<ExampleContext>(
"Restore a database backup",
"This is our procedure for restoring a database backup."
)
.steps(
step("Retrieve the backup file", async (context) => {
const file = await fakeApiCall();
const path = await saveFile(file);
context.backupFilePath = path;
return `Backup downloaded successfully! Saved to \`${context.backupFilePath}\`.`;
}),
step("Load the backup data into the database", async (context) => {
if (!context.backupFilePath) throw new Error("No backup file found");
await importDataFromFile(context.backupFilePath);
return "Backup data imported into database successfully.";
}),
step(
"Check the restored data for consistency",
"Log in to the database and make sure there are recent records in the events table."
)
)
.run();
```
and when this is run:
<p align="center"><img src="/img/automated-demo.gif?raw=true"/></p>
### Documenting a Checkscript
A checkscript can be output as markdown, by calling `document()` instead of `run()`. Demonstrated with the original example:
```TypeScript
import { checkscript, step } from "checkscripts";
checkscript(
"Restore a database backup",
"This is our procedure for restoring a database backup."
)
.steps(
step(
"Retrieve the backup file",
"Log in to the [storage control panel](https://example.com/storage/) and download the latest backup file."
),
step(
"Load the backup data into the database",
"Run this command to load the backup data into the database: `psql < backup_YYYYMMDD.sql`."
),
step(
"Check the restored data for consistency",
"Log in to the database and make sure there are recent records in the events table."
),
)
.document();
```
The output will be:
```markdown
# Restore a database backup
_This is our procedure for restoring a database backup._
## 1. Retrieve the backup file
Log in to the [storage control panel](https://example.com/storage/) and download the latest backup file.
## 2. Load the backup data into the database
Run this command to load the backup data into the database: `psql < backup_YYYYMMDD.sql`.
## 3. Check the restored data for consistency
Log in to the database and make sure there are recent records in the events table.
---
_This document is a [checkscript](https://github.com/gbannerman/checkscripts). It can be run using JavaScript._
```