[ecmascript] (#311) Fix for Unknown error on VROES.import from a missing/invalid module path

docs/versions/latest/Release.md

@@ -172,6 +172,22 @@ org.apache.commons.exec.ExecuteException: Process exited with an error: 1 (Exit
 
 The ABX archetype now compiles successfully.
 
+### *VROES.import from invalid package throws Unknown error*
+
+Fixed an issue with VROES.import() in ecmascript Module.
+
+#### Previous Behavior
+
+VROES import from an invalid module path resulted in Unknown error.
+The Unknown error could not be caught in a try/catch block and was not shown in the logs.
+
+#### New Behavior
+
+VROES import from a missing/invalid module path, or import of non-existing elements of a valid module,
+result in more detailed errors in the logs. No exceptions are thrown by default (as per the existing behaviour)
+but there is an option to alter the error handling behaviour via an optional parameter in import.from().
+
+
 ## Upgrade procedure
 
 [//]: # (Explain in details if something needs to be done)

packages/ecmascript/README.md

@@ -1,7 +1,7 @@
 # ECMAScript library
 The purpose of the library is to provide runtime support for Typescript based projects by handling the export/import features of ECMA script as well as providing implementations for Set, Map and sum of the Array functions.
 
-# Usage
+## Usage
 This library is not to be used directly.
 
 ## Export
@@ -13,28 +13,28 @@ export function myFunction() {}
 export var myVar = 5;
 
 ESModule.export()
-	.named("MyClass", MyClass)
-	.named("myFunction", myFunction)
-	.named("myVar", myVar)
-	.build();
+  .named("MyClass", MyClass)
+  .named("myFunction", myFunction)
+  .named("myVar", myVar)
+  .build();
 ```
 
 Default exports (function)
 ```js
 export default function myFunction() {}
 
 ESModule.export()
-	.default(myFunction)
-	.build();
+  .default(myFunction)
+  .build();
 ```
 
 Default exports (class)
 ```js
 export default class MyClass {}
 
 ESModule.export()
-	.default(MyClass)
-	.build();
+  .default(MyClass)
+  .build();
 ```
 
 ## Import
@@ -62,3 +62,42 @@ Mixed imports
 import defaultExport, { MyClass, myFunction as myFunc } from "module-name";
 var { defaultExport, MyClass, myFunc} = ESModule.import("default", "MyClass", "myFunction").from("module-name");
 ```
+
+Import with relative and base path
+```js
+import defaultExport, { MyClass, myFunction as myFunc } from "module-name";
+// Note: ./ and ../ are supported only at the start of the relative path. Relative paths without base path will result in error
+var { myFunc} = ESModule.import("myFunction").from("../../relative/path", "module-name");
+var { MyClass} = ESModule.import("MyClass").from("./relative/path", "module-name");
+```
+
+Import with custom error handling (default behavior is to log an Error and return null)
+```js
+import defaultExport, { MyClass, myFunction as myFunc } from "module-name";
+// throw the error
+var { myFunc} = ESModule.import("myFunction").from(
+  "module-name",
+  null, // no base path needed when module path is not relative
+  function (error) { 
+    throw typeof error === "string" ? new Error(error) : error;
+  }
+);
+// log the error as warning
+var { myFunc} = ESModule.import("myFunction").from(
+  "module-name",
+  null,
+  function (error) { 
+    System.warn(error.toString());
+    return null; // required
+  }
+);
+// do nothing - e.g. to avoid cluttering the logs when trying several potential module paths
+var { myFunc} = ESModule.import("myFunction").from(
+  "module-name",
+  null,
+  function (error) {
+
+    return null; // required
+  }
+);
+```