Giter VIP home page Giter VIP logo

jitterbit-script's Introduction

Jitterbit Script

tests

Community-made Node.js package for static code analysis and execution of Jitterbit scripts.

Provides language support capabilities for Jitterbit VS Code extension.

Language TypeScript
Platform NodeJS

Usage

Static analysis

Create a typed AST along with detected errors and warnings.

import {Diagnostic, Parser, Typechecker} from 'jitterbit-script';

const script = '<trans> $hi = "hello world!" </trans>';
const diagnostics: Diagnostic[] = [];
const parser = new Parser();

const ast = parser.parse(script, diagnostics);
const analysis = Typechecker.analyze(ast, diagnostics);

The above code should never throw, if it does please raise an issue with a bug report.

Runtime

Execute a script.

import {evaluate, Parser, Scope} from 'jitterbit-script';

async function run(script: string) {
  const parser = new Parser();
  try {
    const ast = parser.parse(script);
    return await evaluate(ast, new Scope());
  } catch(err) {
    // error handling
  }
}

const result = run('<trans> $hi = "hello world!" </trans>');

Disclaimer

Please note this is not official Jitterbit tooling. It does differ in behaviour and support from the original Jitterbit runtimes executing scripts in Jitterbit Harmony.

The static analysis system was redesigned to provide static typing and improve problem reporting for better DX and high quality code development.

Currently the support for runtime APIs is limited. See README for details on runtime API support.

The runtime implementation's behaviour is based on the cloud agent and editor versions below.

Component Version
Cloud agent 11.23.0.9
Jitterbit Studio 10.55.0.27

This repo is a fork of tlaceby/guide-to-interpreters-series.

jitterbit-script's People

Contributors

michal-kapala avatar tlaceby avatar

Watchers

James Cloos avatar  avatar

jitterbit-script's Issues

`date` type

Dates can be stored as objects returned by functions such as Date or Now.

Dependency on:

Implementation

Operators

  • assignments
  • unary operators
  • binary operators

Cross-type interactions

  • number
  • bool
  • string
  • null
  • array
  • dictionary
  • binary
  • date

Functions

Required for release:

Optional for release:

API definitions

Module tracker

Jitterbit function module implementation tracker:

Runtime support matrix

Runtime support roadmap per-module. Some functions may or may not be supported regardless, depending on their functionality and requirements.

All the required modules will be supported on first release, with the exceptions of functions using external Jitterbit objects such as transformations, sources/targets, connectors and alike.

Optional modules could be implemented but are not a requirement for #1.

Module Support status
cache no support
conversion supported
crypto no support
database no support
datetime partial support
debug supported
dict/array partial support
diff no support
email no support
env info no support
file no support
general partial support
instance no support
LDAP no support
log/error supported
logical supported
math supported
NetSuite no support
Salesforce no support
string supported
text no support
XML no support

Add ESLint

The linter is required before 1.0 release.

default script arg identifier support

The script arguments which can be passed via RunScript have _<number> default local identifiers which are always valid and null-initialized at runtime if the corresponding value is not provided. These local variables need not be initalized by ArgumentList.

  • typechecker support
  • runtime support

unary `+` operator

While Jitterbit don't state that in the docs, unary + exists for numbers as a counterpart to -.

As an undocumented feature, the implementation of this behaviour has lower priority.

Example from Jitterbit Studio:

<trans>
$a = 70;
$a -= +69.96;
$a
</trans>

returns 0.0400000000000063.

`array` type

Array objects are equivalent to any[] in TS.

Dependency on:

Implementation

Variables

  • system variables

Operators

  • literals
  • assignments
  • unary operators
  • binary operators
  • member access
    • LHS (write)
    • RHS (read)

Cross-type interactions

  • number
  • bool
  • string
  • null
  • array
  • dictionary
  • binary
  • date

Functions

Required for release:

Optional for release:

static type checking

Important LSP server feature that would allow it to return implicit conversion warnings or type errors without evaluation:

  • unknown return type needed for some functions (such as RunScript) and globals
  • error and warning collection
  • identifier type info collection from AST nodes (variables, function names from call expressions)
  • expression type inference
    • assignments
    • literals
    • local identifiers
    • global/system identifiers
    • binary expressions
    • unary expressions
    • member expressions (dont seem possible without static types of arrays/dicts)
    • block expressions
    • calls (per-function validation)

Challenges

  • signature selection and call argument type validation
  • ArgumentList - the args are uninitialized local identifiers (regular names or _1, _2, _3 etc.), the call should update the env and AST types to unknown
  • #14
  • node return type, impossible to guess without a schema (unknown)
  • type return type, sometimes solved by call arg types, sometimes remains ambiguous
  • arg list length validation to be moved off parser (runtime/typechecker switch needed)

operators implementation

Jitterbit-supported operators implementation.
Operator precedence can be found here.

Assignment

Jitterbit Studio supports 3 assignments:

  • =
  • -=
  • +=

Binary

Math, comparison and logical operators:

  • +
  • -
  • *
  • /
  • ^
  • <
  • >
  • <=
  • >=
  • ==
  • !=
  • && / &
  • || / |

Unary

Jitterbit Studio supports 4 unary operators:

  • !
  • -
  • --
  • ++

Objects

The supported object operators are list literals and member key/index access for lists and dictionaries:

  • {}
  • []

unit tests

Unit tests for each of the modules are a must before #1

Lexer

  • tokenization unit tests

Parser

  • AST validation unit tests
  • error handling tests (behaviour diff between typechecker/runtime)

Typechecker

  • selective AST validation (types, errors and warnings)
  • typical mid-typing error handling

Runtime

Type suites

  • JbNumber
  • JbBool
  • JbString
  • JbNull
  • JbArray
  • JbDictionary
  • JbBinary
  • JbDate

Function module suites

System variable suites

  • initialization

Interpreter E2E

  • real-life script suite (lexer + parser + runtime)

Typechecker E2E

  • real-life script suite (lexer + parser + typechecker)

`binary` type

Binary content used by a variety of functions such as HexToBinary is a separate type.

Dependency on:

Implementation

Operators

  • assignments
  • unary operators
  • binary operators

Cross-type interactions

  • number
  • bool
  • string
  • null
  • array
  • dictionary
  • binary
  • date

Functions

Required for release:

npm package release

The modules should be reorganized into an npm package for convenient use in VS Code extension:

  • runtime values to classes
  • expressions to classes
  • unified Jitterbit API
  • user-level API defined
  • npm modules
  • #6
  • #11
  • #15
  • #16

functions implementation

Jitterbit function API implementation:

  • #12
  • call expressions
    • optional/required arguments
    • evaluation where possible

Literal and operator implementations are prereq for this:

`dictionary` type

Dictionary objects equivalent to TS maps are a separate type.

Dependency on:

Implementation

Operators

  • assignments
  • unary operators
  • binary operators
  • member access
    • LHS (write)
    • RHS (read)

Cross-type interactions

  • number
  • bool
  • string
  • null
  • array
  • dictionary
  • binary
  • date

Functions

Required for release:

Side effects

Dictionaries returned from scripts are implicitly converted to a string representation, e.g.

<trans>
a = Dict();
a["key1"] = "content";
a["key2"] = "more content";
a
</trans>

will return a representation of:

"[key1=>\"content\",key2=>\"more content\"]"

Currently there is no deserialization available for this format.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.