mle-js-plsql-ffi 23.7.0

package/LICENSE.txt

@@ -0,0 +1,35 @@
+Copyright (c) 2024, 2025, 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.

package/README.md

@@ -0,0 +1 @@
+Please consult the installation instructions and documentation on https://oracle-samples.github.io/mle-modules.

package/args.d.ts

@@ -0,0 +1,107 @@
+/**
+Copyright (c) 2024, 2025, 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.
+*/
+/**
+ * Argument description.
+ */
+export type ArgInfo = {
+    /**
+     * The value of the argument.
+     */
+    val?: any;
+    /**
+     * The maximum number of bytes an argument with OUT values can take up.
+     * Default: 200.
+     */
+    maxSize?: number;
+    /**
+     * The argument direction. In almost all cases this is not necessary and the
+     * direction chosen by the FFI should be used.
+     * Accepted values:
+     *  - oracledb.BIND_IN
+     *  - oracledb.BIND_OUT
+     *  - oracledb.BIND_INOUT.
+     */
+    dir?: number;
+    /**
+     * If the type chosen by FFI needs to be changed this property can be used.
+     * This property needs to be set to either an oracledb type constant or to
+     * the name of the database type in case of a user defined named type (e.g.
+     * record or object).
+     * This can be useful to ensure no precision loss when e.g. retrieving
+     * a number (by specifying the oracledb.ORACLE_NUMBER override).
+     * It can also be useful to specify the correct overload if the FFI cannot
+     * determine the correct subprogram to use in a package.
+     * @remarks
+     * Named types are case sensitive.
+     */
+    type?: number | string;
+    /**
+     * The number of array elements to be allocated for a PL/SQL INDEX BY associative array.
+     * @remarks
+     * Needed for all OUT associative array arguments.
+     * INDEX BY VARCHAR2 associative arrays are **not** supported.
+     */
+    maxArraySize?: number;
+};
+/**
+ * This interface represents an argument for a PL/SQL call.
+ * It can act as a value holder for arguments that have an OUT value.
+ * It can also act as an extra information store about the given values.
+ * This could be the type, maxSize, direction or maxArraySize.
+ */
+export interface DBArgument {
+    /**
+     * The JavaScript value of the PL/SQL argument.
+     */
+    val: any;
+}
+/**
+ * Create a new argument, to be used in a subsequent PL/SQL call.
+ * @param info optional argument description.
+ * @returns the JavaScript representation of a PL/SQL argument.
+ */
+export declare function arg(info?: ArgInfo): DBArgument;
+/**
+ * Create a new argument with the given value.
+ * @param value the value of the argument.
+ * @param info optional argument description.
+ * @returns the JavaScript representation of a PL/SQL argument.
+ * @remarks
+ * If info contains a val property it will be ignored.
+ */
+export declare function argOf(value: any, info?: ArgInfo): DBArgument;

package/call-error.d.ts

@@ -0,0 +1,58 @@
+/**
+Copyright (c) 2024, 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.
+*/
+/**
+ * This class represents a PL/SQL exception that occurred during the execution
+ * of a PL/SQL subprogram.
+ * @extends Error
+ */
+export declare class CallError extends Error {
+    #private;
+    /**
+     * The Error type returned by the FFI if an issue occurs.
+     * @param code the Oracle error code
+     * @param msg the error message
+     * @private
+     */
+    constructor(code: number, msg: string);
+    /**
+     * Returns true if this CallError is the given PL/SQL exception.
+     * @param errorCode the Oracle error code of the exception.
+     * @returns whether this instance represents the given PL/SQL exception.
+     */
+    is(errorCode: number): boolean;
+}

package/index.d.ts

@@ -0,0 +1,42 @@
+/**
+Copyright (c) 2024, 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.
+*/
+import { DBArgument, arg, argOf } from './args';
+import { CallError } from './call-error';
+import { resolvePackage, resolveFunction, resolveProcedure } from './resolvers';
+export type { DBArgument };
+export { arg, argOf, CallError, resolvePackage, resolveFunction, resolveProcedure, };

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "mle-js-plsql-ffi",
+  "description": "MLE Foreign Function Interface (FFI): API for calling PL/SQL functionality directly",
+  "types": "index.d.ts",
+  "author": "Oracle",
+  "version": "23.7.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"
+}

package/resolvers.d.ts

@@ -0,0 +1,104 @@
+/**
+Copyright (c) 2024, 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.
+*/
+import { DBSubprogram } from './subprogram-api';
+/**
+ * @categoryDescription Resolve Functions
+ * These functions resolve PL/SQL objects by name.
+ * The name can optionally contain the schema divided by a dot e.g. SCOTT.THING.
+ * If the schema is not given the usual PL/SQL name resolution rules apply.
+ * @module
+ */
+/**
+ * Resolve a PL/SQL package by name.
+ *
+ * @returns a representation of the given package that can be used to interact
+ *          with the PL/SQL package.
+ *
+ * @category Resolve Functions
+ *
+ * @example
+ * ```ts
+ * // Get the JS represenation.
+ * const dbmsRandom = resolvePackage('DBMS_RANDOM');
+ *
+ * // Use the representation.
+ * dbmsRandom.seed(42);
+ * console.log(dbmsRandom.normal());
+ * ```
+ */
+export declare function resolvePackage(name: string): any;
+/**
+ * Resolve a PL/SQL top-level function by name.
+ *
+ * @returns a JavaScript function that will execute the PL/SQL function when
+ * called and returns the PL/SQL return value.
+ *
+ * @category Resolve Functions
+ *
+ * @remarks
+ * Similarly to the SQL driver this package has to deal with translating types
+ * between PL/SQL and JavaScript. Some PL/SQL types can be translated into
+ * multiple JavaScript types, so the return type can be overridden.
+ *
+ * @example
+ * ```ts
+ * // Resolve top-level function.
+ * const exampleFunc = resolveFunction('my_func');
+ * // Execute the PL/SQL function simply by calling the JS function.
+ * const numberResult = exampleFunc(42);
+ * // Override the return type of the function.
+ * const oracleNumberResult = exampleFunc.returns(oracledb.ORACLE_NUMBER)(42);
+ * ```
+ */
+export declare function resolveFunction(name: string): DBSubprogram;
+/**
+ * Resolve a PL/SQL top-level procedure.
+ *
+ * @returns a JavaScript function that will execute the given PL/SQL procedure
+ * when called.
+ *
+ * @category Resolve Functions
+ *
+ * @example
+ * ```ts
+ * // Resolve the procedure
+ * const exampleProcedure = resolveProcedure('my_procedure');
+ * exampleProcedure(42, 23);
+ * ```
+ */
+export declare function resolveProcedure(name: string): DBSubprogram;

package/subprogram-api.d.ts

@@ -0,0 +1,71 @@
+/**
+Copyright (c) 2024, 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.
+*/
+/**
+ * Return type override options.
+ */
+export type ReturnInfo = {
+    /**
+     * The same as {@link ArgInfo.maxSize}.
+     */
+    maxSize?: number;
+    /**
+     * The same as {@link ArgInfo.type}.
+     */
+    type?: number | string;
+    /**
+     * The same as {@link ArgInfo.maxArraySize}.
+     */
+    maxArraySize?: number;
+};
+/**
+ * JavaScript representation of a PL/SQL subprogram.
+ */
+export interface DBSubprogram {
+    (...arg: any[]): any;
+    /**
+     * Override the return type of the subprogram.
+     * If the subprogram being represented is a procedure this has no effect.
+     * @param dbType the database type. This needs to be either an oracledb
+     * type constant or a string containing the name of a user defined database
+     * type (only for named types like records and objects).
+     * If more info needs to be specified {@link ReturnInfo} can be used.
+     * @remarks
+     * Type names are case-sensitive.
+     */
+    overrideReturnType(dbType: number | string | ReturnInfo): DBSubprogram;
+}