Release 23.5

oracle-samples · Aug 30, 2024 · 56a7c4e · 56a7c4e
1 parent ccc66dc
commit 56a7c4e
Show file tree

Hide file tree

Showing 13 changed files with 181 additions and 40 deletions.
diff --git a/README.md b/README.md
@@ -11,6 +11,7 @@ The following JavaScript modules are currently available:
 - MLE PL/SQL Types: [mle-js-plsqltypes][mle-js-plsqltypes]
 - MLE Fetch API polyfill: [mle-js-fetch][mle-js-fetch]
 - MLE Base64 Encoding: [mle-encode-base64][mle-encode-base64]
+- MLE Encodings: [mle-js-encodings][mle-js-encodings]
 
 ## Installation
 You need an Oracle Database to make use of the JavaScript modules provided in the Oracle Database Multilingual Engine (MLE).
@@ -33,6 +34,8 @@ npm install mle-js-oracledb
 npm install mle-js-bindings
 npm install mle-js-plsqltypes
 npm install mle-js-fetch
+npm install mle-encode-base64
+npm install mle-js-encodings
 ```
 
 ## Documentation
@@ -91,33 +94,40 @@ The following table shows which version of module documentation and declarations
 
 | Oracle Database  | Declarations | Documentation |
 | ---------------- | ------------ | ------------- |
-| 23ai | [[email protected]][mle-js-types-234] for Oracle 23.4 <br/> [[email protected]][mle-js-types-233] for Oracle 23.3 <br/> [[email protected]][mle-js-types-232] for Oracle 23.2 - Free | **[mle-js (23ai)][mle-js]** <br/> [mle-js-oracledb (23ai)][mle-js-oracledb] <br/> [mle-js-bindings (23ai)][mle-js-bindings] <br/> [mle-js-plsqltypes (23ai)][mle-js-plsqltypes] <br/> [mle-js-fetch (23ai)][mle-js-fetch] <br/> [mle-encode-base64 (23ai)][mle-encode-base64]|
+| 23ai | [mle-js@23.5.0][mle-js-types-235] for Oracle 23.5 <br/> [mle-js@23.4.0][mle-js-types-234] for Oracle 23.4 <br/> [[email protected]][mle-js-types-233] for Oracle 23.3 <br/> [[email protected]][mle-js-types-232] for Oracle 23.2 - Free | **[mle-js (23ai)][mle-js]** <br/> [mle-js-oracledb (23ai)][mle-js-oracledb] <br/> [mle-js-bindings (23ai)][mle-js-bindings] <br/> [mle-js-plsqltypes (23ai)][mle-js-plsqltypes] <br/> [mle-js-fetch (23ai)][mle-js-fetch] <br/> [mle-encode-base64 (23ai)][mle-encode-base64]|
 | 21c | [[email protected]][mle-js-types-213] | [mle-js-oracledb (21c)][mle-js-oracledb-21c] <br/> [mle-js-bindings (21c)][mle-js-bindings-21c] <br/> [mle-js-plsqltypes (21c)][mle-js-plsqltypes-21c] |
 
 ## Examples
 The following code snippet exemplifies the usage of some of these MLE modules combined.
 For additional examples, please check the module documentation pages or have a look at our [blog article][2].
 
 ```JavaScript
-// imports
-const oracledb = require('mle-js-oracledb');
-const bindings = require('mle-js-bindings');
-const plsqltypes = require("mle-js-plsqltypes");
-
-// Read a large number as an Oracle NUMBER from SQL and add another ORACLE NUMBER to it.
-// mle-js-oracledb is used for reading from SQL and mle-js-plsqltypes is used to construct the second Oracle NUMBER.
-const conn = oracledb.defaultConnection();
-const query = "SELECT 9007199254740992 AS n FROM dual";
-const options = { fetchInfo: { N: { type: oracledb.ORACLE_NUMBER } } };
-const queryResult = conn.execute(query, [], options);
-const OracleNumber = plsqltypes.OracleNumber;
-const result = queryResult.rows[0][0].add(new OracleNumber(7));
-
-// Use mle-js-bindings to export the result of the computation.
-// On the database side, this result could be retrieved using something like `dbms_mle.import_from_mle(ctx, 'result', result);`.
-bindings.exportValue("result", result);
+async function run() {
+    // import modules that do not have global symbols
+    const bindings = await import('mle-js-bindings');
+
+    // Read a large number as an Oracle NUMBER from SQL and add another ORACLE NUMBER to it.
+    // mle-js-oracledb (session) is used for reading from SQL and mle-js-plsqltypes (OracleNumber) is used to construct the second Oracle NUMBER.
+    const query = "SELECT 9007199254740992 AS n FROM dual";
+    const options = { fetchInfo: { N: { type: oracledb.ORACLE_NUMBER } } };
+    const queryResult = session.execute(query, [], options);
+    const result = queryResult.rows[0].N.add(new OracleNumber(7));
+
+    // print result to the console before exporting it
+    console.log(result);
+
+    // Use mle-js-bindings to export the result of the computation.
+    // On the database side, this result could be retrieved using something like `dbms_mle.import_from_mle(ctx, 'result', result);`.
+    bindings.exportValue("result", result);
+}
+run();
 ```
 
+## Building and deploying larger JavaScript projects
+If you plan to use database-side JavaScript at a larger scale, we highly
+recommend to read our blog post on [Linting MLE JavaScript Modules in Continuous
+Integration Pipelines][4].
+
 ## Help
 If you have questions or change requests about MLE, please [create a ticket](./CONTRIBUTING.md) or contact [Oracle Support](https://support.oracle.com).
 
@@ -144,10 +154,12 @@ Released under the Universal Permissive License v1.0 as shown at <https://oss.or
 [mle-js-oracledb-21c]: https://oracle-samples.github.io/mle-modules/docs/mle-js-oracledb/21c "mle-js-oracledb 21c"
 [mle-js-bindings-21c]: https://oracle-samples.github.io/mle-modules/docs/mle-js-bindings/21c "mle-js-bindings 21c"
 [mle-js-plsqltypes-21c]: https://oracle-samples.github.io/mle-modules/docs/mle-js-plsqltypes/21c "mle-js-plsqltypes 21c"
+[mle-js-types-235]: https://www.npmjs.com/package/mle-js/v/23.5.0 "[email protected]"
 [mle-js-types-234]: https://www.npmjs.com/package/mle-js/v/23.4.0 "[email protected]"
 [mle-js-types-233]: https://www.npmjs.com/package/mle-js/v/23.3.0 "[email protected]"
 [mle-js-types-232]: https://www.npmjs.com/package/mle-js/v/23.2.0 "[email protected]"
 [mle-js-types-213]: https://www.npmjs.com/package/mle-js/v/21.3.1 "[email protected]"
 [1]: https://blogs.oracle.com/developers/post/introduction-javascript-oracle-database-23c-free-developer-release "Introduction to JavaScript in Oracle Database 23c Free - Developer Release"
 [2]: https://blogs.oracle.com/apex/post/mle-and-the-future-of-server-side-programming-in-oracle-apex "MLE and the Future of Server-Side Programming in Oracle APEX"
 [3]: https://docs.oracle.com/en/database/oracle/oracle-database "Oracle Database"
+[4]: https://blogs.oracle.com/developers/post/linting-mle-javascript-modules-in-continuous-integration-pipelines "JavaScript CI/CD blog"
diff --git a/THIRD_PARTY_LICENSES.txt b/THIRD_PARTY_LICENSES.txt
@@ -1,7 +1,7 @@
 Third Party Attributions for Code
 
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
-TypeDoc 0.23.19 TypeDoc Contributors
+TypeDoc 0.23.28 TypeDoc Contributors
 (https://github.com/TypeStrong/typedoc/graphs/contributors)
 Apache 2.0
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

diff --git a/declarations/mle-encode-base64/package.json b/declarations/mle-encode-base64/package.json
@@ -3,7 +3,7 @@
   "description": "MLE functions to work with base64 encoded data",
   "types": "mle-encode-base64.d.ts",
   "author": "Oracle",
-  "version": "23.4.0",
+  "version": "23.5.0",
   "license": "UPL-1.0",
   "homepage": "https://oracle-samples.github.io/mle-modules",
   "repository": {

diff --git a/declarations/mle-js-bindings/package.json b/declarations/mle-js-bindings/package.json
@@ -3,7 +3,7 @@
   "description": "MLE Bindings for Oracle Database DBMS_MLE",
   "types": "mle-js-bindings.d.ts",
   "author": "Oracle",
-  "version": "23.4.0",
+  "version": "23.5.0",
   "license": "UPL-1.0",
   "homepage": "https://oracle-samples.github.io/mle-modules",
   "repository": {

diff --git a/declarations/mle-js-encodings/package.json b/declarations/mle-js-encodings/package.json
@@ -3,7 +3,7 @@
   "description": "MLE text encoding API",
   "types": "index.d.ts",
   "author": "Oracle",
-  "version": "23.4.0",
+  "version": "23.5.0",
   "license": "UPL-1.0",
   "homepage": "https://oracle-samples.github.io/mle-modules",
   "repository": {

diff --git a/declarations/mle-js-fetch/package.json b/declarations/mle-js-fetch/package.json
@@ -3,7 +3,7 @@
   "description": "MLE Fetch API polyfill",
   "types": "index.d.ts",
   "author": "Oracle",
-  "version": "23.4.0",
+  "version": "23.5.0",
   "license": "UPL-1.0",
   "homepage": "https://oracle-samples.github.io/mle-modules",
   "repository": {

diff --git a/declarations/mle-js-oracledb/api.d.ts b/declarations/mle-js-oracledb/api.d.ts
@@ -467,17 +467,29 @@ export declare abstract class IConnection {
      * affected by the execution of DML statements, see {@link IExecuteReturn}.
      *
      * See
-     * https://github.com/oracle/node-oracledb/blob/v3.1.0/doc/api.md#-426-connectionexecute
+     * https://node-oracledb.readthedocs.io/en/v6.4.0/api_manual/connection.html#connection.execute
      * for more details.
      *
-     * @param sql SQL statement that is executed. The statement may contain bind
-     * parameters.
+     * @param sql This parameter can either be a string or an object.
+     * If the parameter is a string, then it is the SQL statement to be executed.
+     * The statement may contain bind parameters.
+     *
+     * If the parameter is an object (possible since Oracle 23.5),
+     * it conforms to the {@link IExecuteArgs} interface
+     * and contains the SQL statement to be executed and the bind values.
+     *
+     * This object exposes the SQL statement and values properties to retrieve the SQL string and bind values
+     * The statement may contain bind parameters.
      * @param bindParams needed if there are bind parameters in the SQL
      * statement, see {@link BindParameters}.
      * @param options an optional parameter to execute() that may be used to
      * control statement execution.
      */
     abstract execute(sql: string): IExecuteReturn;
+    /**
+     * @since Oracle 23.5
+     */
+    abstract execute(sql: IExecuteArgs, options?: IExecuteOptions): IExecuteReturn;
     abstract execute(sql: string, bindParams: BindParameters, options?: IExecuteOptions): IExecuteReturn;
     /**
      * This method allows sets of data values to be bound to one DML or PL/SQL
@@ -565,6 +577,21 @@ export declare abstract class IConnection {
      */
     abstract getDbObjectClass(className: string): IDbObjectClass;
 }
+/**
+ * Interface for representing {@link execute} 's argument.
+ *
+ * @since Oracle 23.5
+ */
+export interface IExecuteArgs {
+    /**
+     * The sql text of the statement to be executed.
+     */
+    statement: string;
+    /**
+     * An array that contains bind values.
+     */
+    values: [];
+}
 /**
  * Interface for representing a DbObject attribute.
  *

diff --git a/declarations/mle-js-oracledb/mle-js-oracledb-common.d.ts b/declarations/mle-js-oracledb/mle-js-oracledb-common.d.ts
@@ -55,6 +55,18 @@ export declare class OracleDb {
     ORACLE_TIMESTAMP: number;
     ORACLE_TIMESTAMP_TZ: number;
     UINT8ARRAY: number;
+    /**
+     * @since Oracle 23.4
+     */
+    INT8ARRAY: number;
+    /**
+     * @since Oracle 23.4
+     */
+    FLOAT32ARRAY: number;
+    /**
+     * @since Oracle 23.4
+     */
+    FLOAT64ARRAY: number;
     DB_TYPE_VARCHAR: number;
     DB_TYPE_NUMBER: number;
     DB_TYPE_LONG: number;
@@ -77,6 +89,10 @@ export declare class OracleDb {
     DB_TYPE_NCHAR: number;
     DB_TYPE_NCLOB: number;
     DB_TYPE_JSON: number;
+    /**
+     * @since Oracle 23.3
+     */
+    DB_TYPE_OBJECT: number;
     /**
      * @since Oracle 23.4
      */

diff --git a/declarations/mle-js-oracledb/package.json b/declarations/mle-js-oracledb/package.json
@@ -3,7 +3,7 @@
   "description": "MLE SQL Driver",
   "types": "index.d.ts",
   "author": "Oracle",
-  "version": "23.4.0",
+  "version": "23.5.0",
   "license": "UPL-1.0",
   "homepage": "https://oracle-samples.github.io/mle-modules",
   "repository": {

diff --git a/declarations/mle-js-plsqltypes/mle-js-plsqltypes.d.ts b/declarations/mle-js-plsqltypes/mle-js-plsqltypes.d.ts
@@ -35,6 +35,12 @@ 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.
 */
+/**
+ * declare Operators object
+ *
+ * @since Oracle 23.5
+ */
+declare const OracleNumberOperators: any;
 /**
  * JavaScript API for Oracle type TIMESTAMP.
  */
@@ -62,7 +68,7 @@ export declare const OracleDate: IOracleDate;
 /**
  * JavaScript API for Oracle type NUMBER.
  */
-export declare class OracleNumber {
+export declare class OracleNumber extends OracleNumberOperators {
     private impl;
     /**
      * Construct an OracleNumber from a JavaScript number or a string.
@@ -1196,3 +1202,12 @@ export declare class IOracleDate {
      */
     isValid(): boolean;
 }
+/**
+ * JsonId class is used to represent "_id" field in soda document
+ *
+ * @since Oracle 23.5
+ */
+export declare class JsonId extends Uint8Array {
+    toJSON(): string;
+}
+export {};
diff --git a/declarations/mle-js-plsqltypes/package.json b/declarations/mle-js-plsqltypes/package.json
@@ -3,7 +3,7 @@
   "description": "MLE PL/SQL Types",
   "types": "mle-js-plsqltypes.d.ts",
   "author": "Oracle",
-  "version": "23.4.0",
+  "version": "23.5.0",
   "license": "UPL-1.0",
   "homepage": "https://oracle-samples.github.io/mle-modules",
   "repository": {