JXA

Libraries, both native and runtime injectable, for macOS’ JavasScript for Automation (JXA) system.

Contents

This repository contains two different kind of JXA libraries:

1. Libraries: these are native OSA libraries used with Library(). They are managed as JXA source code but need to be compiled with osacompile before usage (see below).
2. Injections: these are libraries extending the JXA object space. You will need the JXA native library to inject them into the JXA runtime. These are used as is.

Installing the libraries

OSA libraries need to go into a folder recognised by the Library() command on your system (basically here and, starting from macOS 10.11, here). The recommended location is the Script Libraries folder in you user Library.

Note the script files in the Libraries tree need to be compiled to binary OSA script files before usage. You can either download the releases from Github, which contain the native libraries in compiled format, or compile them yourself using osacompile as follows:

osacompile -l JavaScript -o ~/Library/Script Libraries/<name>.scpt <name>.jxa

Injections should be copied to a recognised location “as is”. The injection mechanism of the JXA library expects plain text files, so do not compile these!

Using the libraries

The libraries, once compiled and installed as described above, are directly available to the Library() command in your scripts, i.e.

const parser = Library('TextParser')
const addresses = parser.extractAddresses('Apple, One Apple Park Way, Cupertino, CA 95014.')

The injection libraries need a little two-step:

const jxa = Library('JXA')
var _p = new Function(jxa.source('Path')); _p(); _p = null

This will inject the Path extensions into the Path object.

API

For the API of the individual libraries (either native or injected), see the Wiki.

Compatibility

All scripts are written in ES6 conforming JavaScript. Because the JavaScript Core used in the first OS releases to support JXA, macOS 10.10 (Yosemite) and macOS 10.11 (El Capitan), did not fully support the ES6 feature set, macOS 10.12 (Sierra) or better is required to use the libraries.