Cykelero / tasklemon

Painless automation in JavaScript.

^{🛠 Usage   📚 Learning   ☀️ Samples   💬 Caveats   👩🏿‍💻 Contributing   ❤️ Thanks}

Write scripts that manipulate files, make network requests, get user input, all with a delightfully clear API and exceptional documentation. If you want to script things but don't want to use Bash, Tasklemon is what you've been wishing for all along! ✨

Here's a simple script, written in both Tasklemon and in vanilla Node:

🍋 Tasklemon	✳️ Node.js
home.children.forEach(child => {     if (child.extension === 'tmp') child.delete(); });	const fs = require('fs'); const os = require('os'); const path = require('path');   const homePath = os.homedir(); fs.readdirSync(homePath).forEach(childName => {     if (path.parse(childName).ext === '.tmp') {         const absolutePath = path.join(homePath, childName);         fs.unlinkSync(absolutePath);     } });

And with Tasklemon installed, you can just save this code into a file (say, clean.js) and run it in a single command; no imports, no preprocessing:

$ lemon clean.js

(you can also give the appropriate permissions to your scripts to make them directly executable, if you want; see below in Shebang and runtime pinning)

🛠 Usage

Installing Tasklemon

With Node.js present, install Tasklemon globally by running npm install -g tasklemon. This will make it available as lemon on the command line.

Tasklemon supports macOS, Linux, and (with a few caveats) Windows.

Writing and running a script

To use Tasklemon, write a script and save it into a file, then execute it by running lemon your-script.js.
At runtime, Tasklemon exposes its entry points to your script, so you don't have to import anything. It also wraps all your code in an async function call, so that you can await promises wherever.
To get a feel of what's possible, have a look at the examples below.

Debugging a script

Node.js supports debugging through V8's inspector protocol. To debug a Tasklemon script:

1. Run the script with the --inspect-brk flag specified.
   Make sure the flag is before the script's name, so that it is consumed by Tasklemon itself: lemon --inspect-brk your-script.js
2. Open a compatible client, such as Google Chrome's DevTools, or Visual Studio Code, and connect to the Node process.
   For instance, in Google Chrome, this means navigating to chrome://inspect, then clicking “inspect” under “Remote Target”.

Shebang and runtime pinning

When you run a script for the first time, Tasklemon will insert two lines at the top:

• A shebang, which makes the script executable directly, once it has the proper permissions.
  Apply the permissions using chmod u+x your-script.js, and you will be able to execute the script by running ./your-script.js directly.
• A version header, with the current version number of Tasklemon: this makes sure your script can be properly executed by future versions of the runtime.

📚 Learning

After you've installed Tasklemon, I recommend you look at the examples below. They'll give you a good idea of the main features you'll want to use.

After that, you can use the API reference to find what you need. The reference is approachable, straightforward, and replete with clear examples. Here's a sample of what it looks like:

☀️ Samples

Write and read files

Add some text to a log file in the current working directory:

here.file('events.log').appendLine('Operation complete.');

Read JSON from a file:

const packageInfo = here.file('package.json').getContentAsJSON();
cli.tell(`The current project is ${packageInfo.name}.`);

Use an absolute path:

const directXLog = File('C:/Windows/DirectX.log'); // on Windows, drive letter can be specified
const lastLogDate = directXLog.dateModified;

cli.tell('The last DirectX install happened ' + format.date.relative(lastLogDate) + '.');

Declare script parameters, get the values

cli.accept({
    username: ['--name', String, 'Name of user to add'],
    isAdmin: ['-a', Boolean, 'Make user an admin']
});

console.log(cli.args); // will be {username: 'Rose', isAdmin: true}

Then, run the script:

$ lemon adduser.js -a --name=Rose

Format data for display

Display a relative timestamp:

const logDate = here.file('log.txt').dateModified;
cli.tell(format.date.relative(logDate)); // “3 minutes ago”

Display a number and pluralize its unit:

cli.tell(format.number(1, 'carrot')); // “1.00 carrot”
cli.tell(format.number(4528.5, 'carrot')); // “4,528.50 carrots”

Get JSON from a URL

You can use await at the top level of your scripts.

const tasklemonNpmDetails = await net.getJSON('https://registry.npmjs.org/tasklemon');
const lastReleaseDate = tasklemonNpmDetails.time.modified;

cli.tell('Last Tasklemon release was ' + format.date.relative(lastReleaseDate) + '.');

Use the dedupe npm package

There is no need to ever install, or even import packages prior to using them.

const friendNames = await cli.ask('What are your friends called?', Array);
const uniqueFriendNames = npm.dedupe(friendNames);

cli.tell('Total count of unique friend names: ' + uniqueFriendNames.length);

💬 Caveats

I really want Tasklemon to be terrific, but here are a few ways in which it's not.

• By design, file operations are synchronous—just like in bash scripting, for example. That's great for usability, but you're not going to write concurrent server stuff this way.
• Symlinks aren't very well-supported yet. Just traversing them should be fine, but directly manipulating them will be weird.
• On Windows, a few features are missing, such as permission manipulation.

👩🏿‍💻 Contributing

Want to help build Tasklemon? That'd be lovely!
The simplest way to help is give feedback on what it's like to use Tasklemon. All comments are greatly appreciated! You can open an issue on GitHub, or maybe just drop me a note on Mastodon.

To go one step further, you can directly work on the code.
Clone Tasklemon from Github and run npm install. You can then:

• try out your version of Tasklemon by running source/tasklemon.js some-script.js
• run the tests using npm run test (or npm run watch:test for automatic runs)
• build the api docs using npm run build-docs (or npm run watch:build-docs for automatic builds)

Once you've built something nice, submit it as a pull request to make it public.

❤️ Thanks

Thanks to Fabien Bérini, for his help with making the unix-y parts reasonably sane :)
Thanks to Benoît Zugmeyer, for his input on API design and npm support :)