tatsh / jxa-lib Goto Github PK

View Code? Open in Web Editor NEW

31.0 4.0 3.0 531 KB

Library to simplify use of JXA with ES6 and TypeScript.

Home Page: https://tatsh.github.io/jxa-lib/

TypeScript 96.19% JavaScript 3.81%

jxa applescript typescript es6 javascript

jxa-lib's Introduction

Typings for JXA

This is a set of typings for AppleScript in JavaScript that works on macOS 10.10 and above.

This is a work in progress and is not yet stable.

Build

To run the examples, run webpack in the root of the project. Then Execute dist/main.js like so:

osascript -l JavaScript dist/examples/index.js

A prompt window will appear for the Finder application.

Library

In the lib directory, a helper library is available to make this easier to use in TypeScript (or ES6). It removes prefixes where possible to be more like Swift and removes long method names. Example:

import { FileManager } from "jxa-lib";

const fm = new FileManager();
let attr;
try {
  attr = fm.attributesOfItem("/some-file");
} catch (e) {
  // Instead of having to pass &error (Ref object) like in Objective-C,
  // an exception is thrown
  console.log("Maybe /some-file does not exist?");
}

// attr type is FileAttributes or undefined, which does not have prefixes removed
if (attr) {
  console.log(attr.NSFileGroupOwnerAccountID); // string
  console.log(attr.NSFileModificationDate); // Date object
}

Examples

See the examples directory.

Example with C functions

You do not have to use ObjC.import() because all modules will do this on their own.

import { exit, free, malloc } from "jxa-lib/stdlib";
import { memchr, memset } from "jxa-lib/string";

const size = 32;
const buf = malloc(size); // returns Ref<number>
memset(buf, 0, size);
for (let i = 0, c = "a".charCodeAt(0); i < size; i++, c++) {
  buf[i] = c;
}

const asciiC = "c".charCodeAt(0);
const asciiD = "d".charCodeAt(0);

// memchr() returns Ref<number> or Ref to NULL
const result = memchr(buf, asciiC, size);
if (result[0]) {
  // this will be asciiC or null/undefined
  console.log(result[0] === asciiC); // true
  console.log(result[1] === asciiD); // true

  // Getting result[30] or above is not defined behaviour
}

free(result);

// Do not print the result of the last expression
exit(0);

jxa-lib's People

Contributors

Stargazers

Watchers

Forkers

kid-icarus artoria2e5 pje

jxa-lib's Issues

Support CLI args?

Does your webpack configuration for jxa-lib allow keeping the run function global for passing in CLI arguments?

This library for example has a webpack config file + custom webpack plugin that allows for this: https://github.com/pahund/patricks-little-jxa-helpers

The entire module gets set to main and then the global run function gets defined as such: function run(args) { this.main(args); }.

Make this work like a normal package

npm install jxa-lib inside a project does not result in a usable, importable package from within node_modules.

Update the following to work with this library when npm install works:

nitpicks (or "draft types that i don't have time to check")

whose
ObjC C typing
Byte type guard

`whose` filter on Array

Apple has a whose filter for arrays. It is basically filter with an object predicate.

// documentation only gives string and num; we are guessing here
type JXAPrimitive = string | number | boolean | void
interface JXAWhosePredicateExpression {
  // equals, beginsWith...
}
type JXALogical= '_and' | '_or' | '_not'
interface JXAWhosePredicate {
  [logi: JXALogical]: JXAWhosePredicate[],
  [key: string]?: string | number | boolean | JXAWhosePredicateExpression
}
interface JXAArray<T> extends Array<T>, JXAReadonlyArray<T> {}
interface JXAReadonlyArray<T> extends ReadonlyArray<T> {
    /**
     * Returns the elements of an array that meet the condition specified in a filter predicate.
     */
  whose(predicate: JXAWhosePredicate, thisArg?: any): JXAArray<T>;
}

It is possible that they went forward and changed the entire Array.prototype. In that case just remove the extends BS.

ObjC FFI types

Currently bindFunction and registerSubclass do not have type signatures. Judging from the doc it should resemble:

type ObjCType = string | RefType
type ObjCSignature = [ObjCType, ObjCType []]
interface ObjCClass {
  name: string
  properties: {
    [key: string]: string
  }
  methods: (...x?: any[]) => any | {
    type: ObjCSignature
    implementation: (...x?: any[]) => any
  }
}
namespace ObjC {
  export function bindFunction(name: string, args: ObjCSignature);
  export function registerSubclass(class: ObjCClass);
}

Byte concept

Since Ref operates on bytes (uint8_t), it might be a good idea to define a concept of bytes somewhere so it becomes more clear. We will also need utility functions for reading/writing longer integer types and even floats.

Unfortunately the typing part is not something we can do perfectly right now; see microsoft/TypeScript#15480.