* This is a marker type for records such as table rows or query results. *
* The driver uses plain JavaScript objects to represent table rows for * put operations and as results of get operations and query results. A row * object consists of properties each designating a table field (on input) or * field generated by a query (on output). The property keys must * match their corresponding field names and property values are used as * corresponding field values. The match between the keys and field names * is case-insensitive. For put operations such as {@link NoSQLClient#put}, * the property values must be of a type that maps to the corresponding data * type of the table field as described in {@link FieldValue}. When a row * object is received on output, such as from {@link NoSQLClient#get}, its * value will always conform to the schema of the table from which the it was * received or the implied schema of a query projection. *
* Note the following: *
* Typescript-specific: *
* This type is used as a default for TRow type parameter for APIs * such as {@link NoSQLClient#get}, {@link NoSQLClient#put} and others as well * as interfaces representing the results of these operations. It represents * object of any type. *
* The users are encouraged to define interface or type that describes the * shape of their table rows and use it as TRow type parameter for * these APIs. */ export type AnyRow = { [name: string]: any; }; /** * Typescript-specific. *
* Interface that may be used to add custom type definitions to the set of * values allowed by {@link FieldValue} type. For example, when using 3rd * party number library (see {@link DBNumberConfig}) you can use this * interface to include the 3rd party number type as an allowed * {@link FieldValue} in order to avoid compilation errors. For this, define * dbNumber property as shown in the example below. *
* Use module agumentation to add custom type definitions via this interface
* as shown in the example. Note that it should be sufficient to augment
* oracle-nosql module only once for your application project.
*
* @example
* Using CustomFieldTypes interface for 3rd party number support.
* ```ts
* import type { NoSQLClient } from "oracle-nosqldb";
* import type { Decimal } from "decimal.js";
*
* declare module "oracle-nosqldb" {
* interface CustomFieldTypes {
* dbNumber: Decimal;
* }
* }
*
* async function test(client: NoSQLClient): Promise
* This is a marker type for primary keys, index keys, full or partial. The
* key is represented in the same way as {@link AnyRow}, as plain JavaScript
* object, but only key fields are included.
*
* Typescript-specific:
*
* This type is used as a default for TKey type parameter for APIs
* such as {@link NoSQLClient#get}, {@link NoSQLClient#delete} and others when
* using default value for TRow type parameter (see {@link AnyRow}).
* It represents object of any type.
*
* The users are encouraged to define interface or type that describes the
* shape of their table rows and use it as TRow type parameter for
* these APIs.
*/
export type AnyKey = {
[name: string]: any;
}
/**
* Typescript-specific.
*
* This type is used to infer the primary key type from the row type as
* indicated by the TRow type parameter. As such, it represents all
* possible subsets of properties of TRow that include only
* properties of types that can be used as primary or secondary index keys
* (@see {@link KeyField}).
*
* This type is used as a default value of TKey type parameter for
* APIs that take primary key, such as {@link NoSQLClient#get},
* {@link NoSQLClient#delete} and others. Note that this is only a
* best-effort basis to determine the type of the primary key since the driver
* is not aware of what fields of the table constitute the primary key. You
* can specify the exact shape of the primary key by explicitly providing the
* value of TKey type parameter to these APIs.
*
* If using untyped versions of the above APIs (see {@link AnyRow}), the key
* will be of type {@link AnyKey}.
* @see {@link AnyKey}
* @see {@link AnyRow}
*/
export type RowKey
* Marker type that represents types of field values in a table, which are as
* used property values for rows and primary keys.
*
* FieldValue represents a data item in Oracle NoSQL Database.
* FieldValue objects can be one of several JavaScript and Node.js types,
* the type being dependent on how this value maps onto a given database
* type. For put and other operations where field values are used as input
* their type must be one of the allowable types that maps onto given
* database type (usually being the type of a table field).
*
* FieldValue objects used for put operations are not validated against the
* target table schema in the driver. Validation happens where the table
* schema is available. If an instance does not match the target table an
* error results.
*
* You may specify field value as a (synchronous) function. In this case the
* function will be called with no arguments and its return value will be used
* as the field value. This could be useful if this function is returned from
* a closure context or bound to a class that automatically generates field
* values in some manner.
*
* FieldValue objects returned by the driver (such as from get or query
* operations) always conform to a table schema, or to the shape implied
* by a query projection.
*
* Here we will discuss how JavaScript types map onto the database types and
* vice versa. When field values are used as an input (such as by
* {@link NoSQLClient#put}), some conversions are allowed so there could be
* more than one JavaScript type used for given database type. In this
* instance, we will list preferred JavaScript type first followed by others
* if any. For output field values returned by the driver (such as by
* {@link NoSQLClient#get} and {@link NoSQLClient#query})
* there is a definite JavaScript type used for a given database type. For
* completeness, we will list mappings on input and on output separately.
* Note that for composite database types such as Array, Map, Record and
* JSON, their constituent elements also follow these mappings.
*
* For datatype Number, the driver supports integration with 3rd
* party number libraries such as decimal.js, bignumber.js and others. See
* {@link DBNumberConfig} for details. If this feature is enabled, the
* field value will be an object representing number in the 3rd party
* library, indicated in the table below as "3rd party number". Thus 3rd
* party number will be the output type and preferred input type. If this
* feature is not enabled, the output type and preferred input type will be
* Javascript number. In both cases, you may also use string (representing
* number) as an input type.
*
* Oracle NoSQL Database has a special type JSON NULL, which represents a
* {@link https://www.json.org | JSON} type NULL. JSON NULL may occur as a
* value of a field of Oracle NoSQL Database type JSON or one of its
* subfields that has a value 'null'. JSON NULL value is different and
* separate from SQL NULL. For example, if table MyTable has a field
* info of type JSON, a query such as
* SELECT info.name from MyTable will yield different results for
* records where the value of info.name is null (e.g. if the value of
* info is \{ "name": null \}) with result being JSON NULL and for
* records where the value of the info field itself is NULL
* (SQL NULL), with result being a SQL NULL. In addition, the info
* field itself may take values of SQL NULL or JSON NULL which are distinct
* values, the latter being a value of a JSON type NULL (i.e. the value of
* info is JSON value null). For more details, please see
* {@link https://docs.oracle.com/en/database/other-databases/nosql-database/23.1/sqlreferencefornosql/sql-reference-guide.pdf | SQL Reference Guide}
* and SQL for Oracle NoSQL Database Specification.
*
* The driver represents JSON NULL as JavaScript type null and SQL NULL
* as JavaScript type undefined. When such distinction is not
* important, you may use non-strict comparison (e.g. value == null)
* to determine if the field value is NULL (either SQL or JSON). To
* distinquish between JSON and SQL NULL, use strict comparison (e.g.
* value === undefined). Note that for non-JSON fields, on input you
* may pass either undefined or null, or omit a field alltogether for
* {@link NoSQLClient#put} operations, all of the above being interpreted as
* SQL NULL. For JSON fields, on input you may use either null or undefined
* as a value of the subfield (e.g. info.name) which will be
* interpreted as JSON NULL, but for the field itself (e.g. info)
* null and undefined will be treated as distinct values (JSON NULL and SQL
* NULL correspondingly) as mentioned above.
*
*
* Note the following:
*
* Typescript-specific:
*
* Use the above description as a guide to what types are allowed for use as
* field values. The users are encouraged to create interfaces or types that
* represent the shape of their table rows based on the types described above
* and use them as TRow type parameters for APIs such as
* {@link NoSQLClient#get}, {@link NoSQLClient#put},
* {@link NoSQLClient#delete}, {@link NoSQLClient#writeMany},
* {@link NoSQLClient#query}, etc.
*/
export type FieldValue = AtomicField | FieldValue[] |
{ [name: string]: FieldValue } | Map
*
* Database Type JavaScript Input Type(s) JavaScript
* Output Type
*
* Array Array
* Array
*
*
* Binary Buffer
* Buffer
*
*
* Boolean boolean boolean
*
*
* Double number number
*
*
* Enum string string
*
*
* Fixed Binary Buffer
* Buffer
*
*
* Float number number
*
*
* Integer number number
*
*
* Json object, string, Map
* object
*
*
* Json Null null, undefined (only as sub-field of JSON field)
* null
*
*
* Long number, bigint
* number, bigint
*
*
* Map object, Map object
*
*
* SQL Null undefined (or omit field), null (only for non-JSON fields)
* undefined
*
*
* Number 3rd party number, Javascript number (with limitation), string 3rd party number or Javascript number (with limitation)
*
*
* Record object, Map object
*
*
* String string string
*
*
* Timestamp Date, string
* Date
*
*
*