vs-cron

Visual Studio Code (VS Code) extension that runs tasks periodically.

1. Install
2. How to use
   • Settings
     • Jobs
       • Commands
         • Scripts
   • Commands
3. Documentation

Install [↑]

Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter:

ext install vs-cron

Or search for things like vs-cron in your editor.

How to use [↑]

Settings [↑]

Open (or create) your settings.json in your .vscode subfolder of your workspace.

Add a cron.jobs section:

{
    "cron.jobs": {
    }
}

Name	Description
globals	Global data available from everywhere.
jobs	One or more job to define.
timeZone	The custom default value for the timezone to use.

Jobs [↑]

{
    "cron.jobs": {
        "jobs": [
            {
                "name": "My AutoSave using CronTab format",
                "description": "Saves all opened files all 30 seconds.",

                "time": "*/30 * * * * *",
                "action": "workbench.action.files.saveAll"
            },

            {
                "name": "My Script using specific date",
                "description": "Runs a script at a specific time.",

                "format": "date",
                "time": "1979-09-05 23:09:00",
                "action": {
                    "type": "script",
                    "script": "./my-cron-script.js"
                }
            }
        ]
    }
}

Name	Description
action	The action to define.
autoStart	Run on startup or not. Default: (false)
description	The description for the job.
format	The format to use. Can be crontab or date. Default: crontab
if	One or more conditions (as JavaScript code) that defines if job is available or not.
isFor	An optional list of one or more (host)names that job is available for.
maximum	The maximum number of executions.
minimum	The minimum number of ticks before the job does its first action.
name	The (display) name of the job.
platforms	One or more platform names the job is for. s. process.platform
runParallel	Indicates if this job can be run parallel to another or not. Default: (false)
startDelay	The start delay in milliseconds.
time	The time value that is used to configure the job. For crontab format, s. cron module
timeZone	The custom timezone to use.
validFrom	Defines the minumum time the job can be executed.
validUntil	Defines the maximum time the job can be executed.

Actions [↑]

The action can be a string, for executing a command, or an object with a type property:

Value	Description
command	Execute a command.
script	Execute a script.

Commands [↑]

{
    "cron.jobs": {
        "jobs": [
            {
                "name": "My AutoSave",
                "description": "Saves all opened files all 5 minutes.",

                "time": "*/5 * * * *",
                "action": {
                    "type": "command",
                    "command": "workbench.action.files.saveAll"
                }
            }
        ]
    }
}

The action property has the following format:

Name	Description
arguments	Optional / required arguments for the command.
command	The ID of the command to execute.

Scripts [↑]

{
    "cron.jobs": {
        "globals": "Marcel K! Marcel K! Marcel K!",

        "jobs": [
            {
                "name": "My Script",
                "description": "Runs a script every minute.",

                "action": {
                    "type": "script",
                    "script": "./my-cron-script.js",

                    "options": "TM",
                    "state": 23979
                }
            }
        ]
    }
}

The action property has the following format:

Name	Description
cached	Store script (module) in cache or not. Default: (false)
options	Optional data for the execution.
script	The path to the script to execute.
state	The initial state value for the script.

The ./my-cron-script.js script file must have a public / exported tick() function:

exports.tick = function(args) {
    // access VS Code API (s. https://code.visualstudio.com/Docs/extensionAPI/vscode-api)
    var vscode = require('vscode');

    // access Node.js API provided by VS Code
    // s.  (s. https://nodejs.org/api/)
    var fs = require('fs');

    // access an own module
    var myModule = require('./my-module.js');

    // access a module used by the extension:
    // s. https://mkloubert.github.io/vs-cron/modules/_helpers_.html
    var helpers = args.require('./helpers');

    // access a module that is part of the extentsion
    // s. https://github.com/mkloubert/vs-cron/blob/master/package.json
    var moment = args.require('moment');

    // access the global data from the settings
    // 
    // from the example above this is: "Marcel K! Marcel K! Marcel K!"
    var globals = args.globals;

    // access the data from the settings
    // 
    // from the example above this is: "TM"
    var opts = args.options;

    // share / store data (while current session)...
    // ... for this script
    var myState = args.state;  // 23979 at the beginning (s. settings above)
    args.state = new Date();
    // ... with other scripts of this type
    args.globalState['myScript'] = new Date();

    // access permanent data storages
    // s. https://github.com/Microsoft/vscode/blob/master/src/vs/workbench/common/memento.ts
    var myAppWideValue = args.appState.get('myAppValue');  // app wide
    args.workspaceState.update('myWorkspaceValue', 'New workspace wide value');  // workspace wide

    // share data between two executions
    var prevVal = args.previousValue;  // data from the previous execution
    args.nextValue = 'This is a value only for the next execution';  // data for the next execution

    // registers for a one-time event
    args.once('myEvent', function(v) {
        // 'v' should be 'Anders Hejlsberg'
        // if upcoming 'args.emit()' is called
        args.log("From 'myEvent': " + v);
    });

    // emit 'myEvent' event (s. above)
    args.emit('myEvent', 'Anders Hejlsberg');

    // open HTML document in new tab (for reports e.g.)
    args.openHtml('<html>This is an HTML document</html>', 'My HTML document').then(function() {
        // HTML opened
    }, function(err) {
        // opening HTML document failed
    });

    // deploys 'index.html' to 'My SFTP server'
    // s. https://github.com/mkloubert/vs-deploy
    args.deploy(['./index.html'], ['My SFTP server']).then(function() {
        // file deployed
    }, function(err) {
        // deployment failed
    });

    // ...
}

The args parameter uses the JobScriptModuleExecutorArguments interface.

You can return a number (sync execution), a Promise or nothing (default exit code 0).

Commands [↑]

Press F1 to open the list of commands and enter one of the following commands:

Name	Description	Command
Cron Jobs: Restart all jobs	Restarts all running jobs.	extension.cronJons.restartRunningJobs
Cron Jobs: Restart job	Restarts a specific job.	extension.cronJons.restartJob
Cron Jobs: Start job	Starts a specific job.	extension.cronJons.startJob
Cron Jobs: Start all jobs	Starts all non-running jobs.	extension.cronJons.startNoRunningJobs
Cron Jobs: Stop all running jobs	Stops all running jobs.	extension.cronJons.stopRunningJobs
Cron Jobs: Stop job	Stops a specific job.	extension.cronJons.stopJob

Documentation [↑]

The full API documentation can be found here.