stephancasas / jxa-toolkit

A boilerplate / utility wrapper for JXA (AppleScript JavaScript) scripts — providing common automation functions.

jxa-toolkit

A boilerplate / utility wrapper for JXA (AppleScript JavaScript) scripts — providing common automation functions.

Usage

jxa-toolkit is intended to aid in the creation of JXA scripts which will be run from the command line/shell. The entrypoint is the top-level run() function, which accepts a single argument, argv — rendered as the array of args which are passed via the shell.

Write your automation script's entry code inside of the run() function of src/app.js. You can declare additional functions or variables outside of this function signature, but such declarations will remain dormant unless by a called inside of run().

When ready, use npm run test to compile your script inside of the utility wrapper and execute the outcome (dist/app.jxa). The execution permission will be automatically applied by the compiler script.

📝 NOTE

If you have not previously granted permissions to System Events or Visual Studio Code, macOS may prompt you for additional permissions. You should grant/apply these permissions in System Preferences when prompted.

Functions Reference

Globals

ctx() | Current Application

Description Get the current application context with standard additions included.

Example

// request input from the user
const response = ctx().displayDialog('Do you want to continue?');

---

process(processName) | Application Process by Name

Description Get the application process (of System Events) by its name.

Arguments

Argument	Description
processName	The process name to resolve.

Example

// get the position of a Finder window
const windowPos = process('Finder').windows.at(0).position();

---

exec(...cmd) | Execute Shell Command

Description Execute a shell function — including the current user's environment variables and shell config.

Arguments

Argument	Description
cmd	The command to execute, and any of its arguments.

Example

// execute a nodejs script named "script.js" from the user's Downloads directory
exec('node', Path.resolve(Path.User.DOWNLOADS, 'script.js'));

---

fetchSync(url) | HTTP GET Request

Description Perform a curl GET request against the given url.

Arguments

Argument	Description
url	The request's target url.

Example

// verify whether or not the system is presently connected to the internet by
//   making a request to Apple's captive validation service
const hasInternet = fetchSync('https://captive.apple.com/')
  .toLowerCase()
  .includes('success');

Cursor

Cursor.getPosition(actual) | Current Cursor Position

Description Get the cursor's current coordinates.

Arguments

Argument	Description
actual	Get the cursor's actual position without consideration for display offset (very rare use case).

Example

// get the cursor's current position
const { x, y } = Cursor.getPosition();

---

Cursor.setPosition(x, y, offset) | Set Cursor Position

Description Set the cursor's position using (x, y) coordinates. A default offset of 8x8 is applied. This is done to ensure correct targeting of coordinates provided by querying UI elements directly, but can be overriden by passing null as the third argument.

Arguments

Argument	Description
x	The cursor's target X position.
y	The cursor's target Y position.
offset	The offset, as {x,y}, to apply to the final cursor position.

Example

// move the cursor to the exact position of the first Finder window
const [x, y] = process('Finder')
  .windows.at(0)
  .attributes.byName('AXPosition')
  .value();

Cursor.setPosition(x, y, null);

---

Cursor.click(button) | Click the Cursor

Description Click the cursor at its current position.

Arguments

Argument	Description
button	As 'left' or 'right', the cursor button to click (defaults to 'left').

Example

// move the cursor to the exact position of the first Finder window and click
const [x, y] = process('Finder')
  .windows.at(0)
  .attributes.byName('AXPosition')
  .value();

Cursor.setPosition(x, y, null);
Cursor.click('left');

---

Cursor.setRestore() / Cursor.restore() | Store/Restore the Cursor Position

Description Store the current cursor position for restore later.

Example

// move the cursor to the exact position of the first Finder window and click,
//   then return to the original position
const [x, y] = process('Finder')
  .windows.at(0)
  .attributes.byName('AXPosition')
  .value();

Cursor.setRestore();
Cursor.setPosition(x, y, null);
Cursor.click('left');
Cursor.restore();

File

File.read(path) | Read File Content

Description Read the content of file by its path.

Arguments

Argument	Description
path	The POSIX path to the target file.

Example

// read the contents of a file on the desktop
const data = File.read('~/Desktop/my_file.txt');

---

File.write(path, data) | Write File Content

Description Write data to a file at the given path.

Arguments

Argument	Description
path	The POSIX path to the target file.
data	As a string, the data to write.

Example

// write content to a file on the desktop
const data = 'Stephan hates osascript.';
File.write('~/Desktop/my_file.txt', data);

---

File.delete(path) | Delete a File

Description Delete a file or directory by its path.

Arguments

Argument	Description
path	The POSIX path to the target file or directory.

Example

// delete a file named "my_file.txt" from the desktop
File.delete('~/Desktop/my_file.txt');

// delete a directory named "AppleScript" from the desktop
File.delete('~/Desktop/AppleScript');

---

File.exists(path) | Check File Existence

Description Determine whether or not a file exists at the given path.

Arguments

Argument	Description
path	The POSIX path to the target file.

Example

// perform an operation dependingon whether or not a file named
//  "my_file.txt" exists on the desktop
if (File.exists('~/Desktop/my_file.txt')) {
  // ...
}

Dir

Dir.read(path) | List a Directory's Content

Description Read the content of a directory by its path. An array is returned, with each filename as an element.

Arguments

Argument	Description
path	The POSIX path to the target directory.

Example

// get the name of every file on the desktop
const files = Dir.read('~/Desktop');

---

Dir.make(path) | Make a Directory

Description Make a directory at the given path.

Arguments

Argument	Description
path	The POSIX path to the target creation directory.

Example

// create a directory named "AppleScript" on the desktop
Dir.make('~/Desktop/AppleScript');

Path

Path.resolve(...path) | Resolve an Absolute Path

Description Resolve the absolute location of a given path.

Note This is automatically applied to any File or Dir operations.

Arguments

Argument	Description
path	A single POSIX path to resolve, or its constituents separated into individual args.

Example

// get the path to a directory named "AppleScript" in the
//   current user's pictures directory
const applescript = Path.resolve('~/Pictures', 'AppleScript');
//   → "/Users/johnnyappleseed/Pictures/AppleScript"

---

Path.User.{{...}} | Resolve an Absolute User Path

Description Resolve the absolute location of the current user's home, Desktop, Documents, Downloads, or Library directory.

Variations Path.User.HOME / Path.User.DESKTOP / Path.User.DOCUMENTS / Path.User.DOWNLOADS / Path.User.LIBRARY

Example

// get the path to a file named "script.txt" in the current
//   user's Downloads directory
const applescript = Path.resolve(Path.User.DOWNLOADS, 'script.txt');
//   → "/Users/johnnyappleseed/Downloads/script.txt"

---

Path.System.{{...}} | Resolve an Absolute System Path

Description Resolve the absolute location of the system's Library or tmp (temporary) directory.

Variations

Path.System.LIBRARY / Path.System.TMP

Example

// get the path to a file named "script.txt" in the temporary directory
const applescript = Path.resolve(Path.System.TMP, 'script.txt');
//   → "/tmp/script.txt"

License

MIT -- "Hell, yeah! Free software!"

Contact

👨‍💻	Stephan Casas
📧	stephancasas[at]icloud[dot]com
🐦	@stephancasas
📷	@stephancasas