Release 23.3

oracle-samples · Sep 20, 2023 · f5607a7 · f5607a7
1 parent fecf901
commit f5607a7
Show file tree

Hide file tree

Showing 21 changed files with 607 additions and 167 deletions.
diff --git a/README.md b/README.md
@@ -2,19 +2,21 @@
 The Oracle Database Multilingual Engine (MLE) enables [JavaScript execution in Oracle Database][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 predefined 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.
+While the documentation consists 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.
 
 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]
 - MLE Fetch API polyfill: [mle-js-fetch][mle-js-fetch]
+- MLE Base64 Encoding: [mle-encode-base64][mle-encode-base64]
 
 ## 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.
+A very convenient way of getting an Oracle Database instance is to create an always-free Oracle Cloud account and use it to set up a free autonomous database instance as our [blog article][2] explains in great detail.
 
+### All-In-One Installation (recommended)
 You can install all relevant declarations of these modules plus the declarations of all global symbols (`Polyglot`, `console`, `session`, `soda`, `oracledb`, `OracleNumber`, etc.) in one bundle.
 You can conveniently install `mle-js` from NPM and then reference it in the beginning of your JavaScript code using the `<reference>` tag:
 
@@ -23,7 +25,8 @@ npm install mle-js
 /// <reference types="mle-js" />
 ```
 
-If you only need declarations of a particular module, you can also just install them individually:
+### Installing Individual Modules
+If you only need declarations of a few particular modules, you may also install their declarations individually:
 
 ```
 npm install mle-js-oracledb
@@ -65,20 +68,25 @@ In order to make the Fetch API available, it needs to be imported first.
 
 [Continue reading...][mle-js-fetch]
 
+### MLE functions to work with base64 encoded data (mle-encode-base64)
+This module contains code to work with base64-encoded data.
+
+[Continue reading...][mle-encode-base64]
+
+
 ### 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.
+Oracle Database is the world’s most popular database. Oracle Database 23c, the next Generation Oracle Database, is now available as a Base Database Service delivering the most complete and simple converged database for developers looking to build new microservice, graph, document and relational applications.
+Oracle Database 23c Free is also available for free as a simple download for ease of use.
 
 [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 |
-| ---------------- | --------|
-| 23c | [mle-js@23.2.0][mle-js] <br/> [mle-js-oracledb@23.2.0][mle-js-oracledb] <br/> [mle-js-bindings@23.2.0][mle-js-bindings] <br/> [mle-js-plsqltypes@23.2.0][mle-js-plsqltypes] <br/> [mle-js-fetch@23.2.0][mle-js-fetch] |
-| 21c | [mle-js-oracledb@21.3.0][mle-js-oracledb-21c] <br/> [mle-js-bindings@21.3.0][mle-js-bindings-21c] <br/> [mle-js-plsqltypes@21.3.0][mle-js-plsqltypes-21c] |
+| Oracle Database  | Declarations | Documentation |
+| ---------------- | ------------ | ------------- |
+| 23c | [mle-js@23.3.0][mle-js-types-233] for Oracle 23.3 <br/> [[email protected]][mle-js-types-232] for Oracle 23.2 - Free | **[mle-js (23c)][mle-js]** <br/> [mle-js-oracledb (23c)][mle-js-oracledb] <br/> [mle-js-bindings (23c)][mle-js-bindings] <br/> [mle-js-plsqltypes (23c)][mle-js-plsqltypes] <br/> [mle-js-fetch (23c)][mle-js-fetch] <br/> [mle-encode-base64 (23c)][mle-encode-base64]|
+| 21c | [[email protected].1][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.
@@ -116,18 +124,22 @@ Before submitting a pull request, please [review our contribution guide](./CONTR
 Please consult the [security guide](./SECURITY.md) for our responsible security vulnerability disclosure process.
 
 ## License
-Copyright (c) 2022 Oracle and/or its affiliates.
+Copyright (c) 2022, 2023 Oracle and/or its affiliates.
 
 Released under the Universal Permissive License v1.0 as shown at <https://oss.oracle.com/licenses/upl/>.
 
-[mle-js]: http://oracle-samples.github.io/mle-modules/docs/mle-js/23c "[email protected]"
-[mle-js-oracledb]: http://oracle-samples.github.io/mle-modules/docs/mle-js-oracledb/23c "[email protected]"
-[mle-js-bindings]: http://oracle-samples.github.io/mle-modules/docs/mle-js-bindings/23c "[email protected]"
-[mle-js-plsqltypes]: http://oracle-samples.github.io/mle-modules/docs/mle-js-plsqltypes/23c "[email protected]"
-[mle-js-fetch]: http://oracle-samples.github.io/mle-modules/docs/mle-js-fetch/23c "[email protected]"
-[mle-js-oracledb-21c]: http://oracle-samples.github.io/mle-modules/docs/mle-js-oracledb/21c "[email protected]"
-[mle-js-bindings-21c]: http://oracle-samples.github.io/mle-modules/docs/mle-js-bindings/21c "[email protected]"
-[mle-js-plsqltypes-21c]: http://oracle-samples.github.io/mle-modules/docs/mle-js-plsqltypes/21c "[email protected]"
+[mle-js]: https://oracle-samples.github.io/mle-modules/docs/mle-js/23c "mle-js 23c"
+[mle-js-oracledb]: https://oracle-samples.github.io/mle-modules/docs/mle-js-oracledb/23c "mle-js-oracledb 23c"
+[mle-js-bindings]: https://oracle-samples.github.io/mle-modules/docs/mle-js-bindings/23c "mle-js-bindings 23c"
+[mle-js-plsqltypes]: https://oracle-samples.github.io/mle-modules/docs/mle-js-plsqltypes/23c "mle-js-plsqltypes 23c"
+[mle-js-fetch]: https://oracle-samples.github.io/mle-modules/docs/mle-js-fetch/23c "mle-js-fetch 23c"
+[mle-encode-base64]: https://oracle-samples.github.io/mle-modules/docs/mle-encode-base64/23c "mle-encode-base64 23c"
+[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-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/23/index.html "Oracle Database 23c"
+[3]: https://docs.oracle.com/en/database/oracle/oracle-database "Oracle Database"
diff --git a/declarations/mle-encode-base64/LICENSE.txt b/declarations/mle-encode-base64/LICENSE.txt
@@ -0,0 +1,35 @@
+Copyright (c) 2023, 2023, Oracle and/or its affiliates.
+
+The Universal Permissive License (UPL), Version 1.0
+
+Subject to the condition set forth below, permission is hereby granted to any
+person obtaining a copy of this software, associated documentation and/or data
+(collectively the "Software"), free of charge and under any and all copyright
+rights in the Software, and any and all patent rights owned or freely
+licensable by each licensor hereunder covering either (i) the unmodified
+Software as contributed to or provided by such licensor, or (ii) the Larger
+Works (as defined below), to deal in both
+
+(a) the Software, and
+(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+one is included with the Software (each a "Larger Work" to which the Software
+is contributed by such licensors),
+
+without restriction, including without limitation the rights to copy, create
+derivative works of, display, perform, and distribute the Software and make,
+use, sell, offer for sale, import, export, have made, and have sold the
+Software and the Larger Work(s), and to sublicense the foregoing rights on
+either these or other terms.
+
+This license is subject to the following condition:
+The above copyright notice and either this complete permission notice or at
+a minimum a reference to the UPL must 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.
diff --git a/declarations/mle-encode-base64/README.md b/declarations/mle-encode-base64/README.md
@@ -0,0 +1 @@
+Please consult install instructions and documentation on https://oracle-samples.github.io/mle-modules.
diff --git a/declarations/mle-encode-base64/mle-encode-base64.d.ts b/declarations/mle-encode-base64/mle-encode-base64.d.ts
@@ -0,0 +1,59 @@
+/**
+Copyright (c) 2023, Oracle and/or its affiliates.
+
+The Universal Permissive License (UPL), Version 1.0
+
+Subject to the condition set forth below, permission is hereby granted to any
+person obtaining a copy of this software, associated documentation and/or data
+(collectively the "Software"), free of charge and under any and all copyright
+rights in the Software, and any and all patent rights owned or freely
+licensable by each licensor hereunder covering either (i) the unmodified
+Software as contributed to or provided by such licensor, or (ii) the Larger
+Works (as defined below), to deal in both
+
+(a) the Software, and
+(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+one is included with the Software (each a "Larger Work" to which the Software
+is contributed by such licensors),
+
+without restriction, including without limitation the rights to copy, create
+derivative works of, display, perform, and distribute the Software and make,
+use, sell, offer for sale, import, export, have made, and have sold the
+Software and the Larger Work(s), and to sublicense the foregoing rights on
+either these or other terms.
+
+This license is subject to the following condition:
+The above copyright notice and either this complete permission notice or at
+a minimum a reference to the UPL must 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.
+*/
+/**
+ * Encode a string or a byte buffer into base64.
+ 
+ * The function converts the characters to bytes as if they were ASCII encoded.
+ * Convert the data to an ArrayBuffer first if you need to convert strings with
+ * characters outside the ASCII alphabet.
+ *
+ * @throws Error if the input string contains a character outside of ASCII
+ * @return a string with base64-encoded data
+ *
+ * @since Oracle 23.3
+ */
+export declare function encode(input: string | ArrayBuffer | Uint8Array): string;
+/**
+ * Decode a base64 encoded string.
+ *
+ * @throws Error if the input contains characters outside base64 alphabet or is otherwise invalid.
+ * @return a byte array with the decoded data.
+ *
+ * @since Oracle 23.3
+ */
+export declare function decode(input: string): ArrayBuffer;
diff --git a/declarations/mle-encode-base64/package.json b/declarations/mle-encode-base64/package.json
@@ -0,0 +1,14 @@
+{
+  "name": "mle-encode-base64",
+  "description": "MLE functions to work with base64 encoded data",
+  "types": "mle-encode-base64.d.ts",
+  "author": "Oracle",
+  "version": "23.3.0",
+  "license": "UPL-1.0",
+  "homepage": "https://oracle-samples.github.io/mle-modules",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/oracle-samples/mle-modules"
+  },
+  "bugs": "https://github.com/oracle-samples/mle-modules/issues"
+}
diff --git a/declarations/mle-js-bindings/mle-js-bindings.d.ts b/declarations/mle-js-bindings/mle-js-bindings.d.ts
@@ -56,7 +56,7 @@ export declare enum JSTypes {
     ORACLE_TIMESTAMP = 10,
     /** Type OracleTimeStampTZ */
     ORACLE_TIMESTAMP_TZ = 11,
-    /** Type OracleIntervalYearToDay */
+    /** Type OracleIntervalYearToMonth */
     ORACLE_INTERVAL_YM = 12,
     /** Type OracleIntervalDayToSecond */
     ORACLE_INTERVAL_DS = 13,

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

diff --git a/declarations/mle-js-fetch/body.d.ts b/declarations/mle-js-fetch/body.d.ts
@@ -35,6 +35,13 @@ 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.
 */
+import { IBufferWrapper } from './common';
+/**
+ * Type alias for the types the body can be
+ *
+ * @since Oracle 23.3
+ */
+export type BodyType = IBufferWrapper | ArrayBuffer | string | null;
 export declare class Body {
     #private;
     /**
@@ -44,8 +51,8 @@ export declare class Body {
     /**
      * Retrieve the contents of the body.
      */
-    get body(): string | null;
-    constructor(body?: string | Body | null);
+    get body(): BodyType;
+    constructor(body?: BodyType | Body);
     /**
      * Consume the contents of the body as JSON.
      */
@@ -54,17 +61,14 @@ export declare class Body {
      * Consume the contents of the body as text.
      */
     text(): Promise<string>;
+    arrayBuffer(): Promise<ArrayBuffer>;
     /**
-     * Unsupported operation.
-     */
-    arrayBuffer(): void;
-    /**
-     * Unsupported operation.
+     * Unsupported operation (keep protected until implemented)
      */
-    blob(): void;
+    protected blob(): void;
     /**
-     * Unsupported operation.
+     * Unsupported operation (keep protected until implemented)
      */
-    formData(): void;
-    protected _cloneBodyContent(): string | null;
+    protected formData(): void;
+    protected _cloneBodyContent(): BodyType;
 }
diff --git a/declarations/mle-js-fetch/common.d.ts b/declarations/mle-js-fetch/common.d.ts
@@ -1,5 +1,5 @@
 /**
-Copyright (c) 2022, 2023, Oracle and/or its affiliates.
+Copyright (c) 2023, 2023, Oracle and/or its affiliates.
 
 The Universal Permissive License (UPL), Version 1.0
 
@@ -35,8 +35,11 @@ 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.
 */
-export declare type InitiatorType = 'audio' | 'beacon' | 'body' | 'css' | 'early-hint' | 'embed' | 'fetch' | 'font' | 'frame' | 'iframe' | 'image' | 'img' | 'input' | 'link' | 'object' | 'ping' | 'script' | 'track' | 'video' | 'xmlhttprequest' | 'other';
-export declare type ServiceWorkersMode = 'all' | 'none';
-export declare type Initiator = '' | 'download' | 'imageset' | 'manifest' | 'prefetch' | 'prerender' | 'xslt';
-export declare type Destination = '' | 'audio' | 'audioworklet' | 'document' | 'embed' | 'font' | 'frame' | 'iframe' | 'image' | 'manifest' | 'object' | 'paintworklet' | 'report' | 'script' | 'serviceworker' | 'sharedworker' | 'style' | 'track' | 'video' | 'worker' | 'xslt';
-export declare type ResponseTainting = 'basic' | 'cors' | 'opaque';
+/**
+ * Interface to represent types that provide a view into an ArrayBuffer e.g. DataView
+ *
+ * @since Oracle 23.3
+ */
+export interface IBufferWrapper {
+    buffer: ArrayBuffer;
+}
diff --git a/declarations/mle-js-fetch/headers.d.ts b/declarations/mle-js-fetch/headers.d.ts
@@ -35,7 +35,7 @@ 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.
 */
-export declare type HeadersInit = string[][] | Record<string, string> | Headers;
+export type HeadersInit = string[][] | Record<string, string> | Headers;
 export declare class Headers {
     #private;
     /**

diff --git a/declarations/mle-js-fetch/package.json b/declarations/mle-js-fetch/package.json
@@ -1,14 +1,14 @@
 {
   "name": "mle-js-fetch",
-  "version": "23.2.0",
   "description": "MLE Fetch API polyfill",
   "types": "index.d.ts",
   "author": "Oracle",
+  "version": "23.3.0",
   "license": "UPL-1.0",
   "homepage": "https://oracle-samples.github.io/mle-modules",
   "repository": {
     "type": "git",
     "url": "git://github.com/oracle-samples/mle-modules"
   },
   "bugs": "https://github.com/oracle-samples/mle-modules/issues"
-}
+}
diff --git a/declarations/mle-js-fetch/request.d.ts b/declarations/mle-js-fetch/request.d.ts
@@ -35,12 +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.
 */
-import { Body } from './body';
+import { Body, BodyType } from './body';
 import { Headers, HeadersInit } from './headers';
-export declare type RequestInfo = Request | string;
+export type RequestInfo = Request | string;
 export interface RequestInit {
     method?: string;
-    body?: string;
+    body?: BodyType;
     headers?: HeadersInit;
     credentials?: string;
 }

diff --git a/declarations/mle-js-fetch/response.d.ts b/declarations/mle-js-fetch/response.d.ts
@@ -35,9 +35,9 @@ 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.
 */
-import { Body } from './body';
+import { Body, BodyType } from './body';
 import { Headers } from './headers';
-export declare type ResponseType = 'basic' | 'cors' | 'default' | 'error' | 'opaque' | 'opaqueredirect';
+export type ResponseType = 'basic' | 'cors' | 'default' | 'error' | 'opaque' | 'opaqueredirect';
 export interface ResponseInit {
     status?: number;
     statusText?: string;
@@ -57,7 +57,7 @@ export declare class Response extends Body {
      * @param body the body of the result
      * @param init additional metadata on the result of the retrieval
      */
-    constructor(body?: string | null, init?: ResponseInit);
+    constructor(body?: BodyType, init?: ResponseInit);
     /**
      * Create a new response that represents a network error.
      */
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Please consult install instructions and documentation on https://oracle-samples.github.io/mle-modules.