Release 21.3

Author: lucasbraun

CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing to this repository
+
+We welcome your contributions! There are multiple ways to contribute.
+
+## Opening issues
+
+For bugs or enhancement requests, please file a GitHub issue unless it's
+security related. When filing a bug remember that the better written the bug is,
+the more likely it is to be fixed. If you think you've found a security
+vulnerability, do not raise a GitHub issue and follow the instructions in our
+[security policy](./SECURITY.md).
+
+## Contributing code
+
+We welcome your code contributions. Before submitting code via a pull request,
+you will need to have signed the [Oracle Contributor Agreement][OCA] (OCA) and
+your commits need to include the following line using the name and e-mail
+address you used to sign the OCA:
+
+```text
+Signed-off-by: Your Name <[email protected]>
+```
+
+This can be automatically added to pull requests by committing with `--sign-off`
+or `-s`, e.g.
+
+```text
+git commit --signoff
+```
+
+Only pull requests from committers that can be verified as having signed the OCA
+can be accepted.
+
+## Pull request process
+
+1. Ensure there is an issue created to track and discuss the fix or enhancement
+   you intend to submit.
+1. Fork this repository
+1. Create a branch in your fork to implement the changes. We recommend using
+   the issue number as part of your branch name, e.g. `1234-fixes`
+1. Ensure that any documentation is updated with the changes that are required
+   by your change.
+1. Ensure that any samples are updated if the base image has been changed.
+1. Submit the pull request. *Do not leave the pull request blank*. Explain exactly
+   what your changes are meant to do and provide simple steps on how to validate
+   your changes. Ensure that you reference the issue you created as well.
+1. We will assign the pull request to 2-3 people for review before it is merged.
+
+## Code of conduct
+
+Follow the [Golden Rule](https://en.wikipedia.org/wiki/Golden_Rule). If you'd
+like more specific guidelines, see the [Contributor Covenant Code of Conduct][COC].
+
+[OCA]: https://oca.opensource.oracle.com
+[COC]: https://www.contributor-covenant.org/version/1/4/code-of-conduct/
+

LICENSE renamed to LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2017, 2021, Oracle and/or its affiliates.
+Copyright (c) 2017, 2022, Oracle and/or its affiliates.
 
 The Universal Permissive License (UPL), Version 1.0
 

README.md

@@ -1,15 +1,106 @@
 # MLE Modules
-This repository contains documentation and interface definitions for MLE modules as provided in Oracle Database.
+The Oracle Database Multilingual Engine (MLE) enables [JavaScript execution in Oracle Database as of version 21c][1].
+In this database JavaScript environment, there exist some JavaScript modules that are available out of the box.
+This repository contains documentation and interface definitions (in the form of TypeScript declarations) for those pre-defined modules.
+While the documentation contains set of human-readable, linked pages, the TypeScript declaration files are typically consumed by an IDE for improving auto-completion.
+This is particularly useful in a scenario where JavaScript code gets developed locally in an IDE and then deployed to the database.
 
-## Oracle Database 21c
+The following JavaScript modules are currently available:
+- 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]
 
-### Interface Definitions
-- 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)
+## Installation
+You need an Oracle Database to make use of the JavaScript modules provided in the Oracle Database Multilingual Engine (MLE).
+A very convenient way of getting an Oracle Database instance is to create an always-free Oracle Cloud account and set up a free autonomous database instance there as our [blog article][2] explains in great detail.
 
-### Documentation
-- MLE SQL Driver: [./docs/mle-js-oracledb/21.3.0](./docs/mle-js-oracledb/21.3.0)
-- MLE Bindings: [./docs/mle-js-bindings/21.3.0](./docs/mle-js-bindings/21.3.0)
-- MLE PL/SQL Types [./docs/mle-js-plsqltypes/21.3.0](./docs/mle-js-plsqltypes/21.3.0)
+The declaration files can conveniently be installed into your project directory using NPM:
 
+```
+npm install mle-js-oracledb
+npm install mle-js-bindings
+npm install mle-js-plsqltypes
+```
+
+## Documentation
+
+### MLE SQL Driver (mle-js-oracledb)
+If JavaScript is executed inside the database, SQL statements can be executed using an easy to use SQL driver.
+This driver is built-in into the JavaScript engine in the database.
+
+[Continue reading...][mle-js-oracledb]
+
+### MLE Bindings for Oracle Database `DBMS_MLE` (mle-js-bindings)
+The MLE Bindings module can be used to exchange values between PL/SQL and JavaScript.
+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 PL/SQL Types (mle-js-plsqltypes)
+MLE allows importing SQL values from PL/SQL as well as fetching them from a SQL statement.
+By default, SQL values get converted to JavaScript values during that process, e.g. an Oracle `NUMBER` gets converted to a JavaScript `number`.
+Sometimes it is required to have JavaScript values that behave exactly as if they were SQL values.
+The mle-js-plsqltypes module contains JavaScript APIs for such JavaScript objects that wrap PL/SQL objects.
+
+[Continue reading...][mle-js-plsqltypes]
+
+### Oracle Database
+Oracle Database is the world's most popular database.
+Available on cloud and on-premises platforms, Oracle Database 19c is the most recent long term release, with an extended support window.
+Oracle Database 21c is the latest innovation release, initially available on Oracle cloud through Autonomous Database Free Tier and Database Cloud Service.
+
+[Continue reading...][3]
+
+### Version Mapping
+The following table shows which version of module documentation and declarations work with which version of Oracle Database:
+
+| Oracle Database  | Modules |
+| ---------------- | --------|
+| 21.3, 21.4, etc. | [[email protected]][mle-js-oracledb] <br/> [[email protected]][mle-js-bindings] <br/> [[email protected]][mle-js-plsqltypes] |
+
+## Examples
+The following code snippet exemplifies the usage of all 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);
+```
+
+## Help
+If you have questions or change requests about MLE, please [create a ticket](./CONTRIBUTING.md) or contact [Oracle Support](https://support.oracle.com).
+
+## Contributing
+This project welcomes contributions from the community.
+Before submitting a pull request, please [review our contribution guide](./CONTRIBUTING.md).
+
+## Security
+
+Please consult the [security guide](./SECURITY.md) for our responsible security vulnerability disclosure process.
+
+## License
+Copyright (c) 2022 Oracle and/or its affiliates.
+
+Released under the Universal Permissive License v1.0 as shown at <https://oss.oracle.com/licenses/upl/>.
+
+[mle-js-oracledb]: http://oracle-samples.github.io/mle-modules/docs/mle-js-oracledb/21c "[email protected]"
+[mle-js-bindings]: http://oracle-samples.github.io/mle-modules/docs/mle-js-bindings/21c "[email protected]"
+[mle-js-plsqltypes]: http://oracle-samples.github.io/mle-modules/docs/mle-js-plsqltypes/21c "[email protected]"
+[1]: https://medium.com/graalvm/mle-executing-javascript-in-oracle-database-c545feb1a010 "Multilingual Engine: Executing JavaScript in Oracle Database"
+[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/21/index.html "Oracle Database 21c"

SECURITY.md

@@ -0,0 +1,38 @@
+# Reporting security vulnerabilities
+
+Oracle values the independent security research community and believes that
+responsible disclosure of security vulnerabilities helps us ensure the security
+and privacy of all our users.
+
+Please do NOT raise a GitHub Issue to report a security vulnerability. If you
+believe you have found a security vulnerability, please submit a report to
+[[email protected]][1] preferably with a proof of concept. Please review
+some additional information on [how to report security vulnerabilities to Oracle][2].
+We encourage people who contact Oracle Security to use email encryption using
+[our encryption key][3].
+
+We ask that you do not use other channels or contact the project maintainers
+directly.
+
+Non-vulnerability related security issues including ideas for new or improved
+security features are welcome on GitHub Issues.
+
+## Security updates, alerts and bulletins
+
+Security updates will be released on a regular cadence. Many of our projects
+will typically release security fixes in conjunction with the
+[Oracle Critical Patch Update][3] program. Additional
+information, including past advisories, is available on our [security alerts][4]
+page.
+
+## Security-related information
+
+We will provide security related information such as a threat model, considerations
+for secure use, or any known security issues in our documentation. Please note
+that labs and sample code are intended to demonstrate a concept and may not be
+sufficiently hardened for production use.
+
+[1]: mailto:[email protected]
+[2]: https://www.oracle.com/corporate/security-practices/assurance/vulnerability/reporting.html
+[3]: https://www.oracle.com/security-alerts/encryptionkey.html
+[4]: https://www.oracle.com/security-alerts/

mle-js-bindings/THIRD_PARTY_LICENSES_DEV.txt renamed to THIRD_PARTY_LICENSES.txt

@@ -1,18 +1,15 @@
-Third Party Attributions for Development Code
-
-This file contains dependencies that are used in build scripts, sample code,
-and test suites. These should NOT be needed at runtime by an application built
-using this code.
+Third Party Attributions for Code
 
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
-TypeScript 4.4.3 Microsoft Corp.
+TypeDoc 0.23.19 TypeDoc Contributors
+(https://github.com/TypeStrong/typedoc/graphs/contributors)
 Apache 2.0
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
-TypeDoc 0.22.4 TypeDoc Contributors
-(https://github.com/TypeStrong/typedoc/graphs/contributors)
-Apache 2.0
+Lunr.js 2.3.9 Oliver Nightingale
+(https://github.com/olivernn/lunr.js)
+MIT
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 
 Apache License
@@ -176,3 +173,27 @@ incurred by, or claims asserted against, such Contributor by reason of your
 accepting any such warranty or additional liability.
 
 END OF TERMS AND CONDITIONS
+
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+
+MIT License
+
+Copyright (C) 2013 by Oliver Nightingale
+
+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.