{"id":19584707,"url":"https://github.com/oracle-samples/mle-modules","last_synced_at":"2025-08-08T05:05:17.181Z","repository":{"id":64445428,"uuid":"531435601","full_name":"oracle-samples/mle-modules","owner":"oracle-samples","description":"Documentation and interface declarations for MLE modules as provided in Oracle Database","archived":false,"fork":false,"pushed_at":"2025-07-16T13:17:29.000Z","size":844,"stargazers_count":14,"open_issues_count":2,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-07-30T05:53:00.718Z","etag":null,"topics":["javascript","mle","oracle-database"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"upl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oracle-samples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-09-01T08:46:55.000Z","updated_at":"2025-05-31T03:38:11.000Z","dependencies_parsed_at":"2024-05-02T15:59:31.563Z","dependency_job_id":"a5879bd5-bab2-410d-b0c4-245a273dc8f2","html_url":"https://github.com/oracle-samples/mle-modules","commit_stats":{"total_commits":17,"total_committers":2,"mean_commits":8.5,"dds":"0.17647058823529416","last_synced_commit":"ff322bd34a03c3ff598f0f237edffa3c0cfa55a5"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/oracle-samples/mle-modules","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle-samples%2Fmle-modules","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle-samples%2Fmle-modules/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle-samples%2Fmle-modules/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle-samples%2Fmle-modules/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oracle-samples","download_url":"https://codeload.github.com/oracle-samples/mle-modules/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle-samples%2Fmle-modules/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269366853,"owners_count":24405250,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-08T02:00:09.200Z","response_time":72,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","mle","oracle-database"],"created_at":"2024-11-11T07:49:25.063Z","updated_at":"2025-08-08T05:05:17.143Z","avatar_url":"https://github.com/oracle-samples.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MLE Modules\n\nOracle'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.\n\nThis 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.\n\nThe following JavaScript modules are currently available with Oracle's latest database release:\n\n- MLE SQL Driver: [mle-js-oracledb][mle-js-oracledb]\n- MLE Bindings: [mle-js-bindings][mle-js-bindings]\n- MLE PL/SQL Types: [mle-js-plsqltypes][mle-js-plsqltypes]\n- MLE Fetch API polyfill: [mle-js-fetch][mle-js-fetch]\n- MLE Base64 Encoding: [mle-encode-base64][mle-encode-base64]\n- MLE Encodings: [mle-js-encodings][mle-js-encodings]\n- MLE Foreign Function Interface (FFI): [mle-js-plsql-ffi][mle-js-plsql-ffi]\n\nApart 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.\n\n## Installation\n\nThis section details the both the installing and how to use the supplied typescript declarations in your Project.\n\nYou 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](https://container-registry.oracle.com/ords/ocr/ba/database/free). You can find more details [described in this blog post][5].\n\nThe following sections describe how to use the Typescript declarations with your project.\n\n### All-In-One Installation (recommended)\n\nYou 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:\n```sh\nnpm install --saveDev \"https://github.com/oracle-samples/mle-modules#main\"\n```\n\n### Installing Individual Modules\n\nIf you only need declarations of a particular module, you may also install declarations individually:\n\n```sh\nnpm --saveDev install mle-js-oracledb\nnpm --saveDev install mle-js-bindings\nnpm --saveDev install mle-js-plsqltypes\nnpm --saveDev install mle-js-fetch\nnpm --saveDev install mle-encode-base64\nnpm --saveDev install mle-js-encodings\nnpm --saveDev install mle-js-plsql-ffi\n```\n\n## Documentation\n\nThe following sections cover each declaration file's content, the module it documents, and what you can expect when referencing them in your code.\n\n### All-In-One bundle for MLE modules (mle-js)\n\nThis 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\n\n[Continue reading...][mle-js]\n\n### MLE SQL Driver (mle-js-oracledb)\n\nYou 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.\n\n[Continue reading...][mle-js-oracledb]\n\n### MLE Bindings for Oracle Database `DBMS_MLE` (mle-js-bindings)\n\nThe 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`.\nThe module also takes care of converting values from PL/SQL types to JavaScript types and vice-versa automatically as required.\n\n[Continue reading...][mle-js-bindings]\n\n### MLE PL/SQL Types (mle-js-plsqltypes)\n\nMLE allows importing SQL values from PL/SQL as well as fetching them from a SQL statement.\n\nBy default, SQL values are converted to JavaScript values during that process, e.g. an Oracle `NUMBER` is implicitly converted to a JavaScript `number`.\nSometimes it is required to have JavaScript values that behave exactly as if they were SQL values.\nThe `mle-js-plsqltypes` module contains JavaScript APIs for such JavaScript objects that wrap PL/SQL objects.\n\n[Continue reading...][mle-js-plsqltypes]\n\n### MLE Fetch API polyfill (mle-js-fetch)\n\nMLE offers the following functionality to fetch and upload resources asynchronously across the network: fetch, Headers, Request, Response.\nIn order to make the Fetch API available, it needs to be imported first.\n\n[Continue reading...][mle-js-fetch]\n\n### MLE functions to work with base64 encoded data (mle-encode-base64)\n\nThis module contains code to work with base64-encoded data.\n\n[Continue reading...][mle-encode-base64]\n\n### MLE text encoding API (mle-js-encodings)\n\nThis module is a partial implementation of the Encoding API.\nBy default, TextDecoder and TextEncoder are available in the global namespace and can be used directly.\n\n[Continue reading...][mle-js-encodings]\n\n### MLE Foreign Function Interface (FFI): API for calling PL/SQL functionality directly (mle-js-plsql-ffi)\n\nThis module offers a simple, straight-forward way for interacting with PL/SQL code from within JavaScript.\n\n[Continue reading...][mle-js-plsql-ffi]\n\n### Version Mapping\n\nThe following table shows which version of module documentation and declarations work with which version of Oracle Database:\n\n| Oracle Database  | Declarations | Documentation |\n| ---------------- | ------------ | ------------- |\n| 23ai | [@types/mle-js@23.8.0][mle-js-types-238] for Oracle 23.8 \u003cbr/\u003e [mle-js@23.7.0][mle-js-types-237] for Oracle 23.7 \u003cbr/\u003e [mle-js@23.6.0][mle-js-types-236] for Oracle 23.6 \u003cbr/\u003e [mle-js@23.5.0][mle-js-types-235] for Oracle 23.5 \u003cbr/\u003e [mle-js@23.4.0][mle-js-types-234] for Oracle 23.4 \u003cbr/\u003e [mle-js@23.3.0][mle-js-types-233] for Oracle 23.3 \u003cbr/\u003e [mle-js@23.2.0][mle-js-types-232] for Oracle 23.2 - Free | **[mle-js (23ai)][mle-js]** \u003cbr/\u003e [mle-js-oracledb (23ai)][mle-js-oracledb] \u003cbr/\u003e [mle-js-bindings (23ai)][mle-js-bindings] \u003cbr/\u003e [mle-js-plsqltypes (23ai)][mle-js-plsqltypes] \u003cbr/\u003e [mle-js-fetch (23ai)][mle-js-fetch] \u003cbr/\u003e [mle-encode-base64 (23ai)][mle-encode-base64] \u003cbr/\u003e [mle-js-encodings (23ai)][mle-js-encodings] \u003cbr/\u003e [mle-js-plsql-ffi (23ai)][mle-js-plsql-ffi]|\n| 21c | [mle-js@21.3.1][mle-js-types-213] | [mle-js-oracledb (21c)][mle-js-oracledb-21c] \u003cbr/\u003e [mle-js-bindings (21c)][mle-js-bindings-21c] \u003cbr/\u003e [mle-js-plsqltypes (21c)][mle-js-plsqltypes-21c] |\n\n## Examples\n\nThis section describes how to use the Typescript declarations with MLE/JavaScript as well as some interactive, ad-hoc JavaScript execution.\n\n### Typescript\n\nUsing the Typescript declarations you can create an MLE module as follows.\n\n```typescript\ninterface ISessionMetaData {\n    username: string;\n    oracleVersion: string;\n}\n\n/**\n * A simple JavaScript function fetches the username and database\n * release using the MLE JavaScript SQL driver.\n * \n * @returns an instance of ISessionMetaData\n */\nexport function sessionAndDBInfo(): ISessionMetaData {\n    // instantiate the session meta data\n    const mySession: ISessionMetaData = {\n        username: \"unknown\",\n        oracleVersion: \"unknown\",\n    };\n\n    let sql = `select\n            user`;\n\n    let result = session.execute(sql, [], { outFormat: oracledb.OUT_FORMAT_OBJECT });\n\n    if (result.rows?.length === 1) {\n        mySession.username = result.rows[0].USER;\n    }\n\n    sql = `select\n            version_full\n        from\n            product_component_version`;\n\n    result = session.execute(sql, [], { outFormat: oracledb.OUT_FORMAT_OBJECT });\n\n    if (result.rows?.length === 1) {\n        mySession.oracleVersion = result.rows[0].VERSION_FULL;\n    }\n\n    return mySession;\n}\n```\n\nIn 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](https://www.oracle.com/database/sqldeveloper/technologies/sqlcl/) provides a nice way to do that\n\n```\n$ sql /nolog\n\nSQLcl: Release 24.3 Production on Wed Jan 15 14:16:01 2025\n\nCopyright (c) 1982, 2025, Oracle.  All rights reserved.\n\nSQL\u003e connect app_user@localhost:5432/freepdb1\nPassword? (**********?) ***********\n\nConnected.\n\nSQL\u003e mle create-module -filename ./dist/demo.js -module-name demo_module\nMLE Module demo_module created\n```\n\n### Ad-hoc execution\n\nThe 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.\n\n```sql\nset serveroutput on;\ndeclare\n    l_ctx           dbms_mle.context_handle_t;\n    l_source_code   clob;\nbegin\n    -- Create execution context for MLE execution and provide an environment_\n    l_ctx    := dbms_mle.create_context();\n\n    -- using q-quotes to avoid problems with unwanted string termination\n    l_source_code := \nq'~\n    const result = session.execute(\n        `select 'hello, world'`,\n        [],\n        {\n            outFormat: oracledb.OUT_FORMAT_ARRAY\n        }\n    );\n\n    const message = result.rows[0][0];\n    console.log(message);\n~';\n    dbms_mle.eval(\n        context_handle =\u003e l_ctx,\n        language_id =\u003e 'JAVASCRIPT',\n        source =\u003e l_source_code\n    );\n\n    dbms_mle.drop_context(l_ctx);\nexception\n    when others then\n        dbms_mle.drop_context(l_ctx);\n        raise;\nend;\n/\n```\n\n## Building and deploying larger JavaScript projects\n\nIf 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].\n\n## Changelog\n\n- **Oracle 23.8**\n    - The all-in-one bundle package is now available also under the `@types` scope as `@types/mle-js` through installation directly from GitHub.\n    - Added testing for TypeScript declarations and fixed a number of type bugs and inconsistencies.\n- **Oracle 23.7**\n    - MLE Foreign Function Interface (FFI) for calling PL/SQL functionality directly from JavaScript:\n    [mle-js-plsql-ffi](https://oracle-samples.github.io/mle-modules/docs/mle-js-plsql-ffi/23ai/)\n    - support for setting the [fetchTypeHandler](https://oracle-samples.github.io/mle-modules/docs/mle-js-oracledb/23ai/classes/api.Parameters.html#fetchTypeHandler)\n    in `mle-js-oracledb` / `session.execute` for custom handler functions during result fetching\n- **Oracle 23.6**\n    - improved documentation for OracleNumber\n    [infix operators](https://oracle-samples.github.io/mle-modules/docs/mle-js-plsqltypes/23ai/classes/OracleNumber.html).\n- **Oracle 23.5**\n    - support for\n    [sql-template-tag](https://www.npmjs.com/package/sql-template-tag#oracledb)\n    in SQL execution in `mle-js-oracledb` / `session.execute` by allowing the\n    first argument to be of new type\n    [IExecuteArgs](https://oracle-samples.github.io/mle-modules/docs/mle-js-oracledb/23ai/interfaces/api.IExecuteArgs.html)\n- **Oracle 23.4 (first release of Oracle 23ai)**\n    - support for VECTOR type (INT8ARRAY, FLOAT32ARRAY, FLOAT64, DB_TYPE_VECTOR) in\n    [mle-js-oracledb](https://oracle-samples.github.io/mle-modules/docs/mle-js-oracledb/23ai/modules/api.html)\n    and\n    [mle-js-bindings](https://oracle-samples.github.io/mle-modules/docs/mle-js-bindings/23ai/enums/JSTypes.html)\n    including new\n    [vectorDimensions](https://oracle-samples.github.io/mle-modules/docs/mle-js-oracledb/23ai/interfaces/api.IMetaData.html#vectorDimensions)\n    and\n    [vectorFormat](https://oracle-samples.github.io/mle-modules/docs/mle-js-oracledb/23ai/interfaces/api.IMetaData.html#vectorFormat)\n    meta data properties\n    - support for binding collection types, including new properties\n    [elementTypeClass](https://oracle-samples.github.io/mle-modules/docs/mle-js-oracledb/23ai/classes/api.IDbObjectClass.html#elementTypeClass)\n    and\n    [packageName](https://oracle-samples.github.io/mle-modules/docs/mle-js-oracledb/23ai/classes/api.IDbObjectClass.html#packageName)\n    of `DBObjectClass` and\n    [maxArraySize](https://oracle-samples.github.io/mle-modules/docs/mle-js-oracledb/23ai/interfaces/api.IBindObjectValue.html#maxArraySize)\n    of bind definitions in `mle-js-oracledb`.\n    - support for\n    [keepInStmtCache](https://oracle-samples.github.io/mle-modules/docs/mle-js-oracledb/23ai/interfaces/api.IExecuteOptions.html#keepInStmtCache)\n    option in SQL execution in `mle-js-oracledb` / `session.execute`\n\n## Help\n\nIf you have questions or change requests about MLE, please [create a ticket](./CONTRIBUTING.md) or contact [Oracle Support](https://support.oracle.com). Users of [Oracle Database 23ai Free](https://www.oracle.com/database/free/) can refer to the [Database Free forum](https://forums.oracle.com/ords/apexds/domain/dev-community/category/oracle-database-free).\n\n## Contributing\n\nThis project welcomes contributions from the community.\nBefore submitting a pull request, please [review our contribution guide](./CONTRIBUTING.md).\n\n## Security\n\nPlease consult the [security guide](./SECURITY.md) for our responsible security vulnerability disclosure process.\n\n## License\n\nCopyright (c) 2022, 2025, Oracle and/or its affiliates.\n\nReleased under the Universal Permissive License v1.0 as shown at \u003chttps://oss.oracle.com/licenses/upl/\u003e.\n\n[mle-js]: https://oracle-samples.github.io/mle-modules/docs/mle-js/23ai \"mle-js 23ai\"\n[mle-js-oracledb]: https://oracle-samples.github.io/mle-modules/docs/mle-js-oracledb/23ai \"mle-js-oracledb 23ai\"\n[mle-js-bindings]: https://oracle-samples.github.io/mle-modules/docs/mle-js-bindings/23ai \"mle-js-bindings 23ai\"\n[mle-js-plsqltypes]: https://oracle-samples.github.io/mle-modules/docs/mle-js-plsqltypes/23ai \"mle-js-plsqltypes 23ai\"\n[mle-js-fetch]: https://oracle-samples.github.io/mle-modules/docs/mle-js-fetch/23ai \"mle-js-fetch 23ai\"\n[mle-encode-base64]: https://oracle-samples.github.io/mle-modules/docs/mle-encode-base64/23ai \"mle-encode-base64 23ai\"\n[mle-js-encodings]: https://oracle-samples.github.io/mle-modules/docs/mle-js-encodings/23ai \"mle-js-encodings 23ai\"\n[mle-js-plsql-ffi]: https://oracle-samples.github.io/mle-modules/docs/mle-js-plsql-ffi/23ai \"mle-js-plsql-ffi 23ai\"\n[mle-js-oracledb-21c]: https://oracle-samples.github.io/mle-modules/docs/mle-js-oracledb/21c \"mle-js-oracledb 21c\"\n[mle-js-bindings-21c]: https://oracle-samples.github.io/mle-modules/docs/mle-js-bindings/21c \"mle-js-bindings 21c\"\n[mle-js-plsqltypes-21c]: https://oracle-samples.github.io/mle-modules/docs/mle-js-plsqltypes/21c \"mle-js-plsqltypes 21c\"\n[mle-js-types-238]: https://www.npmjs.com/package/mle-js/v/23.8.0 \"mle-js@23.8.0\"\n[mle-js-types-237]: https://www.npmjs.com/package/mle-js/v/23.7.0 \"mle-js@23.7.0\"\n[mle-js-types-236]: https://www.npmjs.com/package/mle-js/v/23.6.0 \"mle-js@23.6.0\"\n[mle-js-types-235]: https://www.npmjs.com/package/mle-js/v/23.5.0 \"mle-js@23.5.0\"\n[mle-js-types-234]: https://www.npmjs.com/package/mle-js/v/23.4.0 \"mle-js@23.4.0\"\n[mle-js-types-233]: https://www.npmjs.com/package/mle-js/v/23.3.0 \"mle-js@23.3.0\"\n[mle-js-types-232]: https://www.npmjs.com/package/mle-js/v/23.2.0 \"mle-js@23.2.0\"\n[mle-js-types-213]: https://www.npmjs.com/package/mle-js/v/21.3.1 \"mle-js@21.3.1\"\n[1]: https://docs.oracle.com/en/database/oracle/oracle-database/23/mlejs/index.html#Oracle%C2%AE-Database \"Oracle Database JavaScript Developer's Guide\"\n[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\"\n[3]: https://docs.oracle.com/en/database/oracle/oracle-database \"Oracle Database\"\n[4]: https://blogs.oracle.com/developers/post/linting-mle-javascript-modules-in-continuous-integration-pipelines \"JavaScript CI/CD blog\"\n[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\"\n[6]: https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/index.html \"Oracle Database PL/SQL Packages and Types Reference\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foracle-samples%2Fmle-modules","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foracle-samples%2Fmle-modules","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foracle-samples%2Fmle-modules/lists"}