jlens-wasm 0.1.1 → 0.3.0

package/LICENSE

@@ -19,3 +19,29 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+---
+
+Parts of jlens are ported or adapted from the JSONata project (jsonata-js, its
+documentation and the JSONata Exerciser, https://github.com/jsonata-js), which
+is distributed under the following license:
+
+Copyright IBM Corp. 2016, 2020 and JSONata contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -43,5 +43,5 @@ The full guide is the "WebAssembly (browser)" chapter of the jlens book (`docs/s
 
 ## License
 
-MIT. The JSONata test suite and the documentation adapted from JSONata are © IBM Corp. and
-JSONata contributors, also under the MIT license.
+MIT. The code and documentation ported or adapted from JSONata are also under the MIT license;
+see `LICENSE`.

package/jlens.d.ts

@@ -1,8 +1,22 @@
 /* tslint:disable */
 /* eslint-disable */
-/** Variables an expression is evaluated with: `{limit: 10}` defines `$limit`. */
+/**
+ * Variables and functions an expression is evaluated with: `{limit: 10}` defines `$limit`, and
+ * `{rate: (region) => 0.2}` defines `$rate(region)`. Values are converted to JSON; functions are
+ * called as host functions (see `HostFunction`).
+ */
 export type Bindings = Record<string, unknown>;
 
+/**
+ * A JavaScript function called from an expression. Arguments and the result are converted
+ * through JSON: `undefined` stands for undefined, and a function argument arrives as
+ * `undefined`. `this` is `undefined`; use a signature with `-` to receive the context value.
+ * Without a signature, `length` tells higher-order functions how many arguments to pass. An
+ * exception it throws is rethrown by the evaluation, with the `position` and `token` of the call
+ * when it has none. Returning a promise fails with `U1002`.
+ */
+export type HostFunction = (...args: any[]) => unknown;
+
 /** Evaluation guardrails. */
 export interface EvaluateOptions {
     /** Maximum duration of one evaluation, in milliseconds (error `D1012`). */
@@ -279,6 +293,17 @@ export type FunctionCategory =
 | "encoding"
 | "misc";
 
+/** A host function declared to the language service, completed like a built-in function. */
+export interface FunctionDeclaration {
+    /** The name, with or without `$`. */
+    name: string;
+    /** The signature, such as `<n-n?:n>`. */
+    signature?: string;
+    /** Parameter names, without `$`, shown by signature help. */
+    params?: string[];
+    summary?: string;
+}
+
 export interface FunctionInfo {
     /** The name, without `$`. */
     name: string;
@@ -315,16 +340,24 @@ export class Expression {
     bindings?: Bindings | null,
     options?: EvaluateOptions,
     ): string | undefined;
-    /**
-     * Evaluates the expression and records how the result was reached. Evaluation errors are
-     * reported in the returned `error`, not thrown.
-     */
     /**
      * Evaluates the expression against a `Document` converted beforehand, which avoids converting
      * the input on every call. Use it to evaluate several expressions against one document.
      */
     evaluateDocument(document: Document, bindings?: Bindings | null, options?: EvaluateOptions): unknown;
+    /**
+     * Evaluates the expression and records how the result was reached. Evaluation errors are
+     * reported in the returned `error`, not thrown; an exception of a host function is reported
+     * with its `code` (or its `name`) and its `message`.
+     */
     evaluateWithAudit(input?: unknown, bindings?: Bindings | null, options?: AuditOptions): AuditResult;
+    /**
+     * Makes `implementation` available as `$name` in every evaluation, as jsonata-js does. With a
+     * `signature` (such as `<n-n?:n>`), arguments are checked before each call, as for built-in
+     * functions. A function of the same name in the bindings takes precedence. Throws a
+     * `JlensError` when the signature is invalid.
+     */
+    registerFunction(name: string, implementation: HostFunction, signature?: string): void;
     /** The processed syntax tree, as plain objects. */
     ast(): AstNode;
     /** Releases the compiled expression. */
@@ -353,9 +386,14 @@ export class LanguageService {
     /**
      * `schema` describes the input documents; without it, functions and variables are still
      * completed. `variables` declares the bindings the expressions are evaluated with (names with
-     * or without `$`), optionally with a schema for their values.
+     * or without `$`), optionally with a schema for their values. `functions` declares the host
+     * functions they are evaluated with.
      */
-    constructor(schema?: JsonSchema | null, variables?: Record<string, JsonSchema | null>);
+    constructor(
+    schema?: JsonSchema | null,
+    variables?: Record<string, JsonSchema | null> | null,
+    functions?: FunctionDeclaration[] | null,
+    );
     /** Suggestions for the word at `offset`, and the range they replace. */
     complete(text: string, offset: number): Completions;
     /** Syntax errors, and references to fields the schema does not have. */
@@ -412,13 +450,14 @@ export interface InitOutput {
     readonly expression_evaluateJson: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
     readonly expression_evaluateWithAudit: (a: number, b: number, c: number, d: number) => [number, number, number];
     readonly expression_new: (a: number, b: number) => [number, number, number];
+    readonly expression_registerFunction: (a: number, b: number, c: number, d: any, e: number, f: number) => [number, number];
     readonly expression_source: (a: number) => [number, number];
     readonly functions: () => any;
     readonly inferSchema: (a: any, b: number) => [number, number, number];
     readonly languageservice_complete: (a: number, b: number, c: number, d: number) => any;
     readonly languageservice_diagnostics: (a: number, b: number, c: number) => any;
     readonly languageservice_hover: (a: number, b: number, c: number, d: number) => any;
-    readonly languageservice_new: (a: number, b: number) => [number, number, number];
+    readonly languageservice_new: (a: number, b: number, c: number) => [number, number, number];
     readonly languageservice_signatureHelp: (a: number, b: number, c: number, d: number) => any;
     readonly parseRecover: (a: number, b: number) => any;
     readonly version: () => [number, number];

package/jlens.js

@@ -132,7 +132,8 @@ export class Expression {
     }
     /**
      * Evaluates the expression against `input`, a JSON-compatible value (`undefined` means no
-     * input document). `bindings` provides variables: `{limit: 10}` defines `$limit`.
+     * input document). `bindings` provides variables and functions: `{limit: 10}` defines
+     * `$limit`, and `{rate: (region) => ...}` defines `$rate(region)`.
      * Returns `undefined` when the result is undefined; throws a `JlensError` when the
      * evaluation fails.
      * @param {any | null} [input]
@@ -162,6 +163,24 @@ export class Expression {
         ExpressionFinalization.register(this, this.__wbg_ptr, this);
         return this;
     }
+    /**
+     * Makes `implementation` available to the expression as `$name`, in every evaluation. With
+     * a `signature` (such as `<n-n?:n>`), arguments are checked before each call, as for
+     * built-in functions. Throws a `JlensError` when the signature is invalid.
+     * @param {string} name
+     * @param {Function} implementation
+     * @param {string | null} [signature]
+     */
+    registerFunction(name, implementation, signature) {
+        const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        var ptr1 = isLikeNone(signature) ? 0 : passStringToWasm0(signature, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        var len1 = WASM_VECTOR_LEN;
+        const ret = wasm.expression_registerFunction(this.__wbg_ptr, ptr0, len0, implementation, ptr1, len1);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
     /**
      * The source text of the expression.
      * @returns {string}
@@ -234,12 +253,14 @@ export class LanguageService {
     /**
      * Creates a service. `schema` describes the input documents (without it, functions and
      * variables are still completed); `variables` declares the bindings the expressions are
-     * evaluated with, optionally with a schema for their values.
+     * evaluated with, optionally with a schema for their values; `functions` declares the host
+     * functions they are evaluated with.
      * @param {any | null} [schema]
      * @param {any | null} [variables]
+     * @param {any | null} [functions]
      */
-    constructor(schema, variables) {
-        const ret = wasm.languageservice_new(isLikeNone(schema) ? 0 : addToExternrefTable0(schema), isLikeNone(variables) ? 0 : addToExternrefTable0(variables));
+    constructor(schema, variables, functions) {
+        const ret = wasm.languageservice_new(isLikeNone(schema) ? 0 : addToExternrefTable0(schema), isLikeNone(variables) ? 0 : addToExternrefTable0(variables), isLikeNone(functions) ? 0 : addToExternrefTable0(functions));
         if (ret[2]) {
             throw takeFromExternrefTable0(ret[1]);
         }
@@ -327,10 +348,19 @@ function __wbg_get_imports() {
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
+        __wbg___wbindgen_is_function_1f9d30630b8b1d3d: function(arg0) {
+            const ret = typeof(arg0) === 'function';
+            return ret;
+        },
         __wbg___wbindgen_is_null_e343b7d08827ba72: function(arg0) {
             const ret = arg0 === null;
             return ret;
         },
+        __wbg___wbindgen_is_object_3c45d4f2dde4e749: function(arg0) {
+            const val = arg0;
+            const ret = typeof(val) === 'object' && val !== null;
+            return ret;
+        },
         __wbg___wbindgen_is_undefined_8865fb403f8fe9d8: function(arg0) {
             const ret = arg0 === undefined;
             return ret;
@@ -346,6 +376,42 @@ function __wbg_get_imports() {
         __wbg___wbindgen_throw_41e9ee4f547fc59a: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
+        __wbg_apply_a910804df6e1e433: function() { return handleError(function (arg0, arg1, arg2) {
+            const ret = arg0.apply(arg1, arg2);
+            return ret;
+        }, arguments); },
+        __wbg_entries_fb6397112b1de25f: function(arg0) {
+            const ret = Object.entries(arg0);
+            return ret;
+        },
+        __wbg_get_31af05bd4842a84f: function() { return handleError(function (arg0, arg1) {
+            const ret = Reflect.get(arg0, arg1);
+            return ret;
+        }, arguments); },
+        __wbg_get_6c896e0571ddae51: function(arg0, arg1) {
+            const ret = arg0[arg1 >>> 0];
+            return ret;
+        },
+        __wbg_get_unchecked_288889d017702237: function(arg0, arg1) {
+            const ret = arg0[arg1 >>> 0];
+            return ret;
+        },
+        __wbg_has_5d6706e5209576c1: function() { return handleError(function (arg0, arg1) {
+            const ret = Reflect.has(arg0, arg1);
+            return ret;
+        }, arguments); },
+        __wbg_isArray_e15a2ff68ffdbef2: function(arg0) {
+            const ret = Array.isArray(arg0);
+            return ret;
+        },
+        __wbg_length_3121141f8e1c8c58: function(arg0) {
+            const ret = arg0.length;
+            return ret;
+        },
+        __wbg_length_d4bdea10311bd9cf: function(arg0) {
+            const ret = arg0.length;
+            return ret;
+        },
         __wbg_new_2bdcdfcebdfc34d2: function(arg0, arg1) {
             const ret = new TypeError(getStringFromWasm0(arg0, arg1));
             return ret;
@@ -354,6 +420,10 @@ function __wbg_get_imports() {
             const ret = new Error(getStringFromWasm0(arg0, arg1));
             return ret;
         },
+        __wbg_new_ee2291f50781bf1d: function() {
+            const ret = new Array();
+            return ret;
+        },
         __wbg_now_aa4ccb83129e9e55: function() {
             const ret = Date.now();
             return ret;
@@ -370,6 +440,10 @@ function __wbg_get_imports() {
             const ret = arg0.performance;
             return ret;
         },
+        __wbg_push_2baf45db356cf468: function(arg0, arg1) {
+            const ret = arg0.push(arg1);
+            return ret;
+        },
         __wbg_set_145a351398b48c65: function() { return handleError(function (arg0, arg1, arg2) {
             const ret = Reflect.set(arg0, arg1, arg2);
             return ret;
@@ -397,7 +471,12 @@ function __wbg_get_imports() {
             const ret = JSON.stringify(arg0);
             return ret;
         }, arguments); },
-        __wbindgen_generic_0000000000000001: function(arg0, arg1) {
+        __wbindgen_generic_0000000000000001: function(arg0) {
+            // Cast intrinsic for `F64 -> Externref`.
+            const ret = arg0;
+            return ret;
+        },
+        __wbindgen_generic_0000000000000002: function(arg0, arg1) {
             // Cast intrinsic for `Ref(String) -> Externref`.
             const ret = getStringFromWasm0(arg0, arg1);
             return ret;

package/jlens_bg.wasm.d.ts

@@ -12,13 +12,14 @@ export const expression_evaluateDocument: (a: number, b: number, c: number, d: n
 export const expression_evaluateJson: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
 export const expression_evaluateWithAudit: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const expression_new: (a: number, b: number) => [number, number, number];
+export const expression_registerFunction: (a: number, b: number, c: number, d: any, e: number, f: number) => [number, number];
 export const expression_source: (a: number) => [number, number];
 export const functions: () => any;
 export const inferSchema: (a: any, b: number) => [number, number, number];
 export const languageservice_complete: (a: number, b: number, c: number, d: number) => any;
 export const languageservice_diagnostics: (a: number, b: number, c: number) => any;
 export const languageservice_hover: (a: number, b: number, c: number, d: number) => any;
-export const languageservice_new: (a: number, b: number) => [number, number, number];
+export const languageservice_new: (a: number, b: number, c: number) => [number, number, number];
 export const languageservice_signatureHelp: (a: number, b: number, c: number, d: number) => any;
 export const parseRecover: (a: number, b: number) => any;
 export const version: () => [number, number];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jlens-wasm",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "JSONata in WebAssembly, with evaluation audits and schema-driven autocomplete",
   "license": "MIT",
   "repository": {