TypeScript definitions for Bundle of all declarations of pre-defined JavaScript modules that ship with Oracle Database
npm install mle-jsOracle's Multilingual Engine (MLE), powered by GraalVM, enables [JavaScript execution in Oracle Database][1]. Oracle's JavaScript implementation ships with a number of essential JavaScript modules.
This repository contains documentation and interface definitions (in the form of TypeScript declarations) for those predefined modules. While the documentation consists of human-readable, linked pages, the TypeScript declaration files are typically consumed by an IDE. Developers using Oracle's SQL Developer Extension for Visual Studio Code for example benefit from a better developer experience thanks to code-completion, and Typescript checks.
The following JavaScript modules are currently available with Oracle's latest database release:
- MLE SQL Driver: [mle-js-oracledb][mle-js-oracledb]
- MLE Bindings: [mle-js-bindings][mle-js-bindings]
- 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]
- MLE Foreign Function Interface (FFI): [mle-js-plsql-ffi][mle-js-plsql-ffi]
Apart from the modules shipping with the database listed above, you can optionally install modules from community repositories into the database after carefully vetting them with the relevant teams in your organisation.
This section details the both the installing and how to use the supplied typescript declarations in your Project.
You need access to an Oracle Database 23ai system running either on Linux x86-64 or aarch64 to make use of the JavaScript modules provided in Oracle Database Multilingual Engine (MLE). Developers wishing to experiment with MLE can choose from cloud solutions such as Oracle's Always-Free Autonomous Database (Serverless) [see this blog article][2] or use the container images available from container-registry.oracle.com. You can find more details [described in this blog post][5].
The following sections describe how to use the Typescript declarations with your project.
You can install all relevant module declarations including the declarations of all global symbols (Polyglot, console, session, soda, oracledb, OracleNumber, etc.) in one bundle named @types/mle-js by using Node Package Manager (NPM) or a comparable tool:
``sh`
npm install --saveDev "https://github.com/oracle-samples/mle-modules#main"
If you only need declarations of a particular module, you may also install declarations individually:
`sh`
npm --saveDev install mle-js-oracledb
npm --saveDev install mle-js-bindings
npm --saveDev install mle-js-plsqltypes
npm --saveDev install mle-js-fetch
npm --saveDev install mle-encode-base64
npm --saveDev install mle-js-encodings
npm --saveDev install mle-js-plsql-ffi
The following sections cover each declaration file's content, the module it documents, and what you can expect when referencing them in your code.
This bundle contains all relevant declarations of predefined JavaScript modules that ship with the database plus the declarations of all global symbols. Most users should start with this file
[Continue reading...][mle-js]
You use the SQL Driver to interact with the database. You can perform any operation with the MLE SQL Driver that you would SQL and PL/SQL for. If you prefer a more JavaScript-like experience working with the Database API [see PL/SQL Packages and Types Reference][6] you should also have a look at the Foreign Function Interface (FFI) below.
[Continue reading...][mle-js-oracledb]
The MLE Bindings module can be used to exchange values between PL/SQL and JavaScript and is mostly used for Dynamic MLE Execution based on DBMS_MLE.
The module also takes care of converting values from PL/SQL types to JavaScript types and vice-versa automatically as required.
[Continue reading...][mle-js-bindings]
MLE allows importing SQL values from PL/SQL as well as fetching them from a SQL statement.
By default, SQL values are converted to JavaScript values during that process, e.g. an Oracle NUMBER is implicitly converted to a JavaScript number.mle-js-plsqltypes
Sometimes it is required to have JavaScript values that behave exactly as if they were SQL values.
The module contains JavaScript APIs for such JavaScript objects that wrap PL/SQL objects.
[Continue reading...][mle-js-plsqltypes]
MLE offers the following functionality to fetch and upload resources asynchronously across the network: fetch, Headers, Request, Response.
In order to make the Fetch API available, it needs to be imported first.
[Continue reading...][mle-js-fetch]
This module contains code to work with base64-encoded data.
[Continue reading...][mle-encode-base64]
This module is a partial implementation of the Encoding API.
By default, TextDecoder and TextEncoder are available in the global namespace and can be used directly.
[Continue reading...][mle-js-encodings]
This module offers a simple, straight-forward way for interacting with PL/SQL code from within JavaScript.
[Continue reading...][mle-js-plsql-ffi]
The following table shows which version of module documentation and declarations work with which version of Oracle Database:
| Oracle Database | Declarations | Documentation |
| ---------------- | ------------ | ------------- |
| 23ai | [@types/mle-js@23.8.0][mle-js-types-238] for Oracle 23.8
[mle-js@23.7.0][mle-js-types-237] for Oracle 23.7
[mle-js@23.6.0][mle-js-types-236] for Oracle 23.6
[mle-js@23.5.0][mle-js-types-235] for Oracle 23.5
[mle-js@23.4.0][mle-js-types-234] for Oracle 23.4
[mle-js@23.3.0][mle-js-types-233] for Oracle 23.3
[mle-js@23.2.0][mle-js-types-232] for Oracle 23.2 - Free | [mle-js (23ai)][mle-js]
[mle-js-oracledb (23ai)][mle-js-oracledb]
[mle-js-bindings (23ai)][mle-js-bindings]
[mle-js-plsqltypes (23ai)][mle-js-plsqltypes]
[mle-js-fetch (23ai)][mle-js-fetch]
[mle-encode-base64 (23ai)][mle-encode-base64]
[mle-js-encodings (23ai)][mle-js-encodings]
[mle-js-plsql-ffi (23ai)][mle-js-plsql-ffi]|
| 21c | [mle-js@21.3.1][mle-js-types-213] | [mle-js-oracledb (21c)][mle-js-oracledb-21c]
[mle-js-bindings (21c)][mle-js-bindings-21c]
[mle-js-plsqltypes (21c)][mle-js-plsqltypes-21c] |
This section describes how to use the Typescript declarations with MLE/JavaScript as well as some interactive, ad-hoc JavaScript execution.
Using the Typescript declarations you can create an MLE module as follows.
`typescript
interface ISessionMetaData {
username: string;
oracleVersion: string;
}
/**
* A simple JavaScript function fetches the username and database
* release using the MLE JavaScript SQL driver.
*
* @returns an instance of ISessionMetaData
*/
export function sessionAndDBInfo(): ISessionMetaData {
// instantiate the session meta data
const mySession: ISessionMetaData = {
username: "unknown",
oracleVersion: "unknown",
};
let sql = select
user;
let result = session.execute(sql, [], { outFormat: oracledb.OUT_FORMAT_OBJECT });
if (result.rows?.length === 1) {
mySession.username = result.rows[0].USER;
}
sql = select
version_full
from
product_component_version;
result = session.execute(sql, [], { outFormat: oracledb.OUT_FORMAT_OBJECT });
if (result.rows?.length === 1) {
mySession.oracleVersion = result.rows[0].VERSION_FULL;
}
return mySession;
}
`
In the next step you need to transpile the Typescript code to JavaScript. The resulting file can be imported to the Oracle database. SQL Command Line provides a nice way to do that
`
$ sql /nolog
SQLcl: Release 24.3 Production on Wed Jan 15 14:16:01 2025
Copyright (c) 1982, 2025, Oracle. All rights reserved.
SQL> connect app_user@localhost:5432/freepdb1
Password? (?) *
Connected.
SQL> mle create-module -filename ./dist/demo.js -module-name demo_module
MLE Module demo_module created
`
The following snippet can be run in SQLcl, SQL*Plus, and Oracle SQL Developer Extension for Visual Studio Code. The invocation of the SQL code differs from the Typescript example by using the objects stored in the global scope.
`sql
set serveroutput on;
declare
l_ctx dbms_mle.context_handle_t;
l_source_code clob;
begin
-- Create execution context for MLE execution and provide an environment_
l_ctx := dbms_mle.create_context();
-- using q-quotes to avoid problems with unwanted string termination
l_source_code :=
q'~
const result = session.execute(
select 'hello, world',
[],
{
outFormat: oracledb.OUT_FORMAT_ARRAY
}
);
const message = result.rows[0][0];
console.log(message);
~';
dbms_mle.eval(
context_handle => l_ctx,
language_id => 'JAVASCRIPT',
source => l_source_code
);
dbms_mle.drop_context(l_ctx);
exception
when others then
dbms_mle.drop_context(l_ctx);
raise;
end;
/
`
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].
- Oracle 23.8
- The all-in-one bundle package is now available also under the @types scope as @types/mle-js through installation directly from GitHub.mle-js-oracledb
- Added testing for TypeScript declarations and fixed a number of type bugs and inconsistencies.
- Oracle 23.7
- MLE Foreign Function Interface (FFI) for calling PL/SQL functionality directly from JavaScript:
mle-js-plsql-ffi
- support for setting the fetchTypeHandler
in / session.execute for custom handler functions during result fetchingmle-js-oracledb
- Oracle 23.6
- improved documentation for OracleNumber
infix operators.
- Oracle 23.5
- support for
sql-template-tag
in SQL execution in / session.execute by allowing theDBObjectClass
first argument to be of new type
IExecuteArgs
- Oracle 23.4 (first release of Oracle 23ai)
- support for VECTOR type (INT8ARRAY, FLOAT32ARRAY, FLOAT64, DB_TYPE_VECTOR) in
mle-js-oracledb
and
mle-js-bindings
including new
vectorDimensions
and
vectorFormat
meta data properties
- support for binding collection types, including new properties
elementTypeClass
and
packageName
of andmle-js-oracledb
maxArraySize
of bind definitions in .mle-js-oracledb
- support for
keepInStmtCache
option in SQL execution in / session.execute`
If you have questions or change requests about MLE, please create a ticket or contact Oracle Support. Users of Oracle Database 23ai Free can refer to the Database Free forum.
This project welcomes contributions from the community.
Before submitting a pull request, please review our contribution guide.
Please consult the security guide for our responsible security vulnerability disclosure process.
Copyright (c) 2022, 2025, Oracle and/or its affiliates.
Released under the Universal Permissive License v1.0 as shown at
[mle-js]: https://oracle-samples.github.io/mle-modules/docs/mle-js/23ai "mle-js 23ai"
[mle-js-oracledb]: https://oracle-samples.github.io/mle-modules/docs/mle-js-oracledb/23ai "mle-js-oracledb 23ai"
[mle-js-bindings]: https://oracle-samples.github.io/mle-modules/docs/mle-js-bindings/23ai "mle-js-bindings 23ai"
[mle-js-plsqltypes]: https://oracle-samples.github.io/mle-modules/docs/mle-js-plsqltypes/23ai "mle-js-plsqltypes 23ai"
[mle-js-fetch]: https://oracle-samples.github.io/mle-modules/docs/mle-js-fetch/23ai "mle-js-fetch 23ai"
[mle-encode-base64]: https://oracle-samples.github.io/mle-modules/docs/mle-encode-base64/23ai "mle-encode-base64 23ai"
[mle-js-encodings]: https://oracle-samples.github.io/mle-modules/docs/mle-js-encodings/23ai "mle-js-encodings 23ai"
[mle-js-plsql-ffi]: https://oracle-samples.github.io/mle-modules/docs/mle-js-plsql-ffi/23ai "mle-js-plsql-ffi 23ai"
[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-238]: https://www.npmjs.com/package/mle-js/v/23.8.0 "mle-js@23.8.0"
[mle-js-types-237]: https://www.npmjs.com/package/mle-js/v/23.7.0 "mle-js@23.7.0"
[mle-js-types-236]: https://www.npmjs.com/package/mle-js/v/23.6.0 "mle-js@23.6.0"
[mle-js-types-235]: https://www.npmjs.com/package/mle-js/v/23.5.0 "mle-js@23.5.0"
[mle-js-types-234]: https://www.npmjs.com/package/mle-js/v/23.4.0 "mle-js@23.4.0"
[mle-js-types-233]: https://www.npmjs.com/package/mle-js/v/23.3.0 "mle-js@23.3.0"
[mle-js-types-232]: https://www.npmjs.com/package/mle-js/v/23.2.0 "mle-js@23.2.0"
[mle-js-types-213]: https://www.npmjs.com/package/mle-js/v/21.3.1 "mle-js@21.3.1"
[1]: https://docs.oracle.com/en/database/oracle/oracle-database/23/mlejs/index.html#Oracle%C2%AE-Database "Oracle Database JavaScript Developer's Guide"
[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"
[5]: https://blogs.oracle.com/developers/post/fastpath-to-developing-with-oracle-application-express-and-multilingual-engine "Fast-path to developing with Oracle Application Express and Multilingual Engine"
[6]: https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/index.html "Oracle Database PL/SQL Packages and Types Reference"