TypeScript Definition File

[jadonk]

From @troywweber7 on August 9, 2017 0:10

I might submit this as a pull request at a later date, but I've started a typescript definition file for this project. The definition file is incomplete and might not be perfect as I am not intimately familiar with all the shapes in this library yet. But to whomever it helps, you can plop this file in your project and start using bonescript in TS (more easily than without).

Save as BoneScript.d.ts in your project:

/**
 * Created by Troy W. on 08/08/17.
 * Contributors:
 */

/**
 * Most of this was generated by observing the object output when importing bonescript to the node.js interpeter.
 *
 * Definitions were modified from the API documentation (https://github.com/jadonk/bonescript), through observation
 * of the source code, and through experimentation.
 *
 * TODO functions with non-described args and returns haven't been tested/written yet --- TWW
 */

declare module 'bonescript'
{
    import * as VError from 'verror';

    import * as SerialPort from 'serialport';

    // OBJECTS

    export const bone:IBoneObj;

    // FUNCTIONS - TODO obliterate all "any" types where possible! --- TWW

    // https://github.com/jadonk/bonescript#system

    export function getPlatform(callback:(error:ErrorType, platform:any) => void):void;
    export function getPlatform():any;

    export function getEeproms(callback:(error:ErrorType, eeproms:any) => void):void;
    export function getEeproms():any;

    export function echo(data:any, callback:(error:ErrorType, data:any) => void):void;
    export function echo(data:any):any;

    export function readTextFile(filename:string, callback:(error:ErrorType, data:any) => void):void;
    export function readTextFile(filename:string):any;

    export function writeTextFile(filename:string, data:any, callback:(error:ErrorType, data:any) => void):void;
    export function writeTextFile(filename:string, data:any):void;

    export function setDate(date:any, callback:(error:ErrorType, data:any) => void):void;
    export function setDate(date:any):void;

    // https://github.com/jadonk/bonescript#digital-and-analog-io

    export function analogRead(pin:string, callback:(err:ErrorType, value:number) => void):void;
    export function analogRead(pin:string):number;

    export function analogWrite(pin:string, value:number, freq?:number, callback:ErrorCb):void;
    export function analogWrite(pin:string, value:number, freq?:number):void;

    export function attachInterrupt(pin:string, handler:InterruptHandlerFn, mode:InterruptType, callback:ErrorCb):void;
    export function attachInterrupt(pin:string, handler:InterruptHandlerFn, mode:InterruptType):void;

    export function detachInterrupt(pin:string, callback:ErrorCb):void;
    export function detachInterrupt(pin:string):void;

    export function digitalRead(pin:string, callback:(err:ErrorType, value:number) => void):void;
    export function digitalRead(pin:string):number;

    export function digitalWrite(pin:string, value:PinStateType, callback:ErrorCb):void;
    export function digitalWrite(pin:string, value:PinStateType):void;

    export function pinMode(pin:string, direction:any, mux?:any, pullup?:any, slew?:any, callback:ErrorCb):void;
    export function pinMode(pin:string, direction:any, mux?:any, pullup?:any, slew?:any):void;

    export function getPinMode(pin:string, callback:(err:ErrorType, mode:IPinModeObj) => void):void;
    export function getPinMode(pin:string):IPinModeObj;

    export function shiftOut(dataPin:any, clockPin:any, bitOrder:any, val:any, callback:ErrorCb):void;
    export function shiftOut(dataPin:any, clockPin:any, bitOrder:any, val:any):void;

    // https://github.com/jadonk/bonescript#serial

    export function serialOpen(port:any, options:any, callback:ErrorCb):void;
    export function serialOpen(port:any, options:any):void;

    export function serialWrite(port:any, data:any, callback:ErrorCb):void;
    export function serialWrite(port:any, data:any):void;

    export const serialParsers:SerialPort.parsers;

    // https://github.com/jadonk/bonescript#i2c

    export function i2cOpen(port:any, address:any, options:any, callback:ErrorCb):void;
    export function i2cOpen(port:any, address:any, options:any):void;

    export function i2cScan(port:any, callback:ErrorCb):void;
    export function i2cScan(port:any):void;

    export function i2cWriteByte(port:any, byte:any, callback:ErrorCb):void;
    export function i2cWriteByte(port:any, byte:any):void;

    export function i2cWriteBytes(port:any, command:any, bytes:any, callback:ErrorCb):void;
    export function i2cWriteBytes(port:any, command:any, bytes:any):void;

    export function i2cReadByte(port:any, callback:ErrorCb):void;
    export function i2cReadByte(port:any):void;

    export function i2cReadBytes(port:any, command:any, length:any, callback:ErrorCb):void;
    export function i2cReadBytes(port:any, command:any, length:any):void;

    export function i2cStream(port:any, command:any, length:any, callback:ErrorCb):void;
    export function i2cStream(port:any, command:any, length:any):void;

    // https://github.com/jadonk/bonescript#bitsbytes-math-trigonometry-and-random-numbers

    export function lowByte(value:number):number;

    export function highByte(value:number):number;

    export function bitRead(value:number, bitnum:number):number;

    export function bitWrite(value:number, bitnum:number, bitdata:any):number;

    export function bitSet(value:number, bitnum:number):number;

    export function bitClear(value:number, bitnum:number):number;

    export function bit(bitnum:number):number;

    export function min(x:number, y:number):number;

    export function max(x:number, y:number):number;

    export function abs(x:number):number;

    export function constrain(x:number, a:number, b:number):number;

    export function map(value:number, fromLow:number, fromHigh:number, toLow:number, toHigh:number):number;

    export function pow(x:number, y:number):number;

    export function sqrt(x:number):number;

    export function sin(radians:number):number;

    export function cos(radians:number):number;

    export function tan(radians:number):number;

    export function randomSeed(x:number):number;

    export function random(min:number, max:number):number;
    export function random(max:number):number;

    // UNDOCUMENTED API

    export function delay(...args:any[]):any;

    export function autorun(...args:any[]):any;

    export function serverStart(...args:any[]):any;

    export function socketJSReqHandler(...args:any[]):any;

    export function addSocketListeners(...args:any[]):any;

    export function setGlobals(...args:any[]):any;

    // CONSTANTS

    export const OUTPUT:'out';
    export const INPUT:'in';
    export const INPUT_PULLUP:'in_pullup';
    export const ANALOG_OUTPUT:'analog_out';
    export const HIGH:1;
    export const LOW:0;
    export const LSBFIRST:1;
    export const MSBFIRST:0;
    export const CHANGE:'both';
    export const RISING:'rising';
    export const FALLING:'falling';

    // INTERFACES - adjusted based on observation / testing

    interface IPinModeObj
    {
        pin:string;
        name:string;
        modes:string[];
        gpio?:{
            active:boolean,
            direction:'in'|'out',
            allocated:boolean,
        };
        pwm?:{
            freq:number,
            value:number,
        };
        pinState:string;
        mux?:number;
        slew?:'fast'|'slow';
        rx?:'enabled'|'disabled';
        pullup?:'diabled'|'pullup'|'pulldown';
    }

    interface IPinData
    {
        pin:IPinInfo&{ exists:boolean };
        value:number;
    }

    interface IBoneObj
    {
        pins:IPinsObj;
        pinIndex:IPinInfo[];
        uarts:IUartsObj;
        i2c:II2cObj;
    }

    interface IPinsObj
    {
        [i:string]:IPinInfo
    }

    interface IUartsObj
    {
        [i:string]:IUartInfo;
    }

    interface II2cObj
    {
        [i:string]:II2cInfo;
    }

    interface IPinInfo
    {
        // All
        name:string;
        key:string;

        // GPIO / LEDs
        gpio?:number;
        mux?:string;
        muxRegOffset?:string;
        options?:string[];
        universalName?:string;

        // GPIO / LEDs / Analog In
        eeprom?:number;

        // Analog In
        ain?:number;
        scale?:number;

        // LEDs
        led?:string;

        // PWM
        pwm?:IPwmInfo;
    }

    interface IPwmInfo
    {
        module:string;
        sysfs:number;
        index:number;
        muxmode:number;
        path:string;
        name:string;
        chip:string;
        addr:string;
    }

    interface IUartInfo
    {
        devicetree?:string;
        rx?:string;
        tx?:string;
    }

    interface II2cInfo
    {
        devicetree?:string;
        path?:string;
        sda?:string;
        scl?:string;
    }

    // TYPES - adjusted based on observation / testing

    type PinStateType = typeof HIGH|typeof LOW;

    type PinModeType = typeof ANALOG_OUTPUT|typeof INPUT|typeof INPUT_PULLUP|typeof OUTPUT;

    type InterruptType = typeof RISING|typeof FALLING|typeof CHANGE;

    type ErrorCb = (err:ErrorType) => void;

    type InterruptHandlerFn = (err:ErrorType, resp:IPinData) => void;

    type ErrorType = VError.VError|null;
}

To whomever is more familiar with the shapes in this library than I, please give me feedback or fill in the missing/improper shapes.

Copied from original issue: jadonk/bonescript#151

[jadonk]

From @troywweber7 on August 15, 2017 16:27

I'm also not an expert at writing typescript definitions, so I may have gone about it wrong. Open to criticism.

[jadonk]

@troywweber7 this is pretty cool. Sorry I'm just now getting around to checking it out. I've got some urgent bugs/features to add for Blue/PocketBeagle support, but will try to get this in for my next major release.

[jadonk]

From @troywweber7 on December 29, 2017 21:57

@jadonk eventually I intend to submit this to DefinitelyTyped repository so anyone can npm i -D @types/bonescript. However, as I should probably confirm all the shapes before I do. And when someone does submit it to DT, they would likely ping you on their repo for input anyway.

Ultimately, definitely typed recommends bundling the type definition file in your project if possible. To do that, one would just add an entry to package.json for { "types" : "path/to/index.d.ts" }. But that is of course up to the project maintainer, and a lot of JS library maintainers opt not to bundle because they don't want the responsibility of updating the definition file when they update the api.

Anyway, as a final thought (for now), I'm using it in multiple projects, so I have cheated for now and am temporarily hosting here and it can be installed in a project with npm i -D bitbucket:webercode/types-bonescript.

Cheers.