@thegrotesk/scripterra

Welcome to Scripterra 👋

------------------------------------------------------------------
  _________            .__        __
 /   _____/ ___________|__|______/  |_  _______________________
 \_____  \_/ ___\_  __ \  \____ \   __\/ __ \_  __ \_  __ \__  \
 /        \  \___|  | \/  |  |_> >  | \  ___/|  | \/|  | \// __ \_
/_______  /\___  >__|  |__|   __/|__|  \___  >__|   |__|  (____  /
        \/     \/         |__|             \/                  \/
-------------------------------------------------------------------

Powerful script engine for Node.js

🏠 Homepage

🧑‍🏫 Motivation

Most developers sooner or later come across writing scripts that are not directly integrated into the application code.

Thus, tones of javascript files are created that are not related to each other. They perform a certain action, for example, according to the schedule, they get information from a third-party api and write it to the database or something like that.

It's not a bad approach when there are no more than 5 such files. But let's imagine that there are 30 such files? Each separate file is a separate javascript code that does something on a schedule or on a call.

• What about the dependencies?

• What about the dubbing of the code?

• What about the logs?

• What if you have many projects that require one script but different configs for it?

To solve these problems, the Scripterra scripting engine was developed, which removes the need to worry about dubbing, configs, deploy and cron.

🌟 Features

• Pretty CLI
• Multiple env files for one scripts
• Schedules
• Custom detached worker
• Logs
• Easy to use

⚓ Requirments

• redis-stack-server Quick start
• node v16.16.0

⚙️ Install

npm i -g @thegrotesk/scripterra

📌 Quick Guide

You can list all available flags by typing this command:

scripterra --help

Step 1. Init project

Create a project directory and initialize the npm.

mkdir ./my-scripterra-project
cd ./my-scripterra-project
npm init -y

Once it completed, let's create scripterra config file!

scripterra --create config

Your project structure should look like this example:

-my-scripterra-project
|__ .scripterra
|__ package.json
|__ package-lock.json

Step 2. Configure

Open .scripterra file. You should see this template:

SCRIPTS_PATH=./scripts/
ENV_PATH=./env/
REDIS=redis://localhost:6379
LOG_PATH=./logs/

You can change configuration if you want.

SCRIPTS_PATH - define the folder in which you want to store scripts

ENV_PATH - define the folder in which you want to store environment files

REDIS - define redis connection string

LOG_PATH - define the folder in which Scripterra Worker will store the logs

Step 3. Create script

scripterra --create script --name Test

Scripterra will automaticaly create SCRIPTS_PATH folder and store Test.js there.

Step 4. Run script

You can run script with different env files from your ENV_PATH.

Let's create one.

nano ./env/.test

And create some values. For example:

HELLO_STRING=Hello world!

Now open Test.js and log this value. All env values stored in process.env

import { Script } from '@thegrotesk/scripterra';

//Generated by Scripterra.
export class Test extends Script {
    constructor(console, args) {
        super(console, args);
    }

    async main() {
        this.console.consoleInfo(process.env.HELLO_STRING);
    }
}

Now, we can run the script.

scripterra --run Test --env .test

You should see this in your terminal:

------------------------------------------------------------------
  _________            .__        __
 /   _____/ ___________|__|______/  |_  _______________________
 \_____  \_/ ___\_  __ \  \____ \   __\/ __ \_  __ \_  __ \__  \
 /        \  \___|  | \/  |  |_> >  | \  ___/|  | \/|  | \// __ \_
/_______  /\___  >__|  |__|   __/|__|  \___  >__|   |__|  (____  /
        \/     \/         |__|             \/                  \/
-------------------------------------------------------------------
Welcome to Scripterra! Pass --help for more information.

[ 2022-08-12T10:44:37.206Z ]
Info |  Current .scripterra config:
[ 2022-08-12T10:44:37.206Z ]
┌──────────────┬──────────────────────────┐
│   (index)    │          Values          │
├──────────────┼──────────────────────────┤
│ SCRIPTS_PATH │       './scripts/'       │
│   ENV_PATH   │         './env/'         │
│    REDIS     │ 'redis://localhost:6379' │
│   LOG_PATH   │        './logs/'         │
└──────────────┴──────────────────────────┘
[ 2022-08-12T10:44:37.217Z ]
Info |  Compile script...
[Test.js] | Info | Starting...
[Test.js] | Info | Hello world!
[Test.js] | Info | Finished.

Step 5. Schedule script

You can schedule your scripts. Be shure that your redis server is working!

scripterra --schedule Test --env .test --expression '* * * * *'

Check if you schedule was created.

scripterra --listall

You should see this:

Info |  List of all schedules:
[ 2022-08-12T10:49:15.474Z ]
┌─────────┬────────┬─────────┬─────────────┬─────────────────┐
│ (index) │ script │   env   │ expression  │ serialized_task │
├─────────┼────────┼─────────┼─────────────┼─────────────────┤
│    0    │ 'Test' │ '.test' │ '* * * * *' │       ''        │
└─────────┴────────┴─────────┴─────────────┴─────────────────┘

To update schedule cron expression, just type the same command as for creation and update expression string

scripterra --schedule Test --env .test --expresion '10 * * * *'

You should see this message:

Warning | This script and env already scheduled. Updating schedule...

Now, we can launch the scripterra worker to process the jobs.

scripterra -w

Or, you can run worker in detach mode

scripterra -w -D

You should see this:

Info |  Detached worker was started with pid 25052

To stop worker you need to kill the process with pid 25052.

Worker will write logs in LOG_PATH. All logs sorted by pid.

-/logs
|__ scripterra.pid-25052.log

Step 6. Delete the script or schedule

If you want to delete your script. Type:

scripterra --delete script --name Test

If you want to delete your schedule. Type:

scripterra --delete schedule --name Test --env .test

Warning! To delete schedule you need to specify --env flag. Otherwise all schedules for this script will be deleted.

Enjoy!

🧾 Documantation

• About

Run tests

npm run test

Author

👤 Alexander Poberezhnyi

• Github: @TheGrotesk
• LinkedIn: @alexandr-poberezhnyi-90a0a5186

🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check issues page. You can also take a look at the contributing guide.

Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © 2021 Alexander Poberezhnyi. This project is GPL--3.0--or--later licensed.