tasklemon
v0.6.0
Published
Painless automation in JavaScript
Downloads
117
Readme
🛠 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:
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:
- 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
- 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 tochrome://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 usingchmod 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
(ornpm run watch:test
for automatic runs) - build the api docs using
npm run build-docs
(ornpm 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 :)