@ragestudio/scylla-odm 0.22.2 → 0.22.3

package/driver/mapping/doc-info-adapter.js

@@ -0,0 +1,171 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import errors from "../errors.js"
+import utils from "../utils.js"
+
+/**
+ * Provides utility methods to adapt and map user provided docInfo and executionOptions to a predictable object format.
+ * @ignore
+ */
+class DocInfoAdapter {
+	/**
+	 * Returns an Array where each item contains the property name, the column name and the property value (to obtain
+	 * the operator).
+	 * When docInfo.fields is specified, it uses that array to obtain the information.
+	 * @param {Array<String>} docKeys
+	 * @param {null|{fields}} docInfo
+	 * @param {Object} doc
+	 * @param {ModelMappingInfo} mappingInfo
+	 * @returns {Array}
+	 */
+	static getPropertiesInfo(docKeys, docInfo, doc, mappingInfo) {
+		let propertyKeys = docKeys
+		if (docInfo && docInfo.fields && docInfo.fields.length > 0) {
+			propertyKeys = docInfo.fields
+		}
+
+		return propertyKeys.map((propertyName) => ({
+			propertyName,
+			columnName: mappingInfo.getColumnName(propertyName),
+			value: doc[propertyName],
+			fromModel: mappingInfo.getFromModelFn(propertyName),
+		}))
+	}
+
+	/**
+	 * @param {{orderBy}} docInfo
+	 * @param {ModelMappingInfo} mappingInfo
+	 * @returns {Array<String>}
+	 */
+	static adaptOrderBy(docInfo, mappingInfo) {
+		if (!docInfo || !docInfo.orderBy) {
+			return utils.emptyArray
+		}
+		return Object.keys(docInfo.orderBy).map((key) => {
+			const value = docInfo.orderBy[key]
+			const ordering =
+				typeof value === "string" ? value.toUpperCase() : value
+			if (ordering !== "ASC" && ordering !== "DESC") {
+				throw new errors.ArgumentError(
+					'Order must be either "ASC" or "DESC", obtained: ' + value,
+				)
+			}
+			return [mappingInfo.getColumnName(key), ordering]
+		})
+	}
+
+	/**
+	 * Returns the QueryOptions for an INSERT/UPDATE/DELETE statement.
+	 * @param {Object|String|undefined} executionOptions
+	 * @param {Boolean} isIdempotent
+	 */
+	static adaptOptions(executionOptions, isIdempotent) {
+		const options = {
+			prepare: true,
+			executionProfile: undefined,
+			timestamp: undefined,
+			isIdempotent: isIdempotent,
+		}
+
+		if (typeof executionOptions === "string") {
+			options.executionProfile = executionOptions
+		} else if (
+			executionOptions !== null &&
+			executionOptions !== undefined
+		) {
+			options.executionProfile = executionOptions.executionProfile
+			options.timestamp = executionOptions.timestamp
+
+			if (executionOptions.isIdempotent !== undefined) {
+				options.isIdempotent = executionOptions.isIdempotent
+			}
+		}
+		return options
+	}
+
+	/**
+	 * Returns the QueryOptions for a SELECT statement.
+	 * @param {Object|String|undefined} executionOptions
+	 * @param {Boolean} [overrideIdempotency]
+	 */
+	static adaptAllOptions(executionOptions, overrideIdempotency) {
+		const options = {
+			prepare: true,
+			executionProfile: undefined,
+			fetchSize: undefined,
+			pageState: undefined,
+			timestamp: undefined,
+			isIdempotent: undefined,
+		}
+
+		if (typeof executionOptions === "string") {
+			options.executionProfile = executionOptions
+		} else if (
+			executionOptions !== null &&
+			executionOptions !== undefined
+		) {
+			options.executionProfile = executionOptions.executionProfile
+			options.fetchSize = executionOptions.fetchSize
+			options.pageState = executionOptions.pageState
+			options.timestamp = executionOptions.timestamp
+			options.isIdempotent = executionOptions.isIdempotent
+		}
+
+		if (overrideIdempotency) {
+			options.isIdempotent = true
+		}
+
+		return options
+	}
+
+	/**
+	 * Returns the QueryOptions for a batch statement.
+	 * @param {Object|String|undefined} executionOptions
+	 * @param {Boolean} isIdempotent
+	 * @param {Boolean} isCounter
+	 */
+	static adaptBatchOptions(executionOptions, isIdempotent, isCounter) {
+		const options = {
+			prepare: true,
+			executionProfile: undefined,
+			timestamp: undefined,
+			logged: undefined,
+			isIdempotent: isIdempotent,
+			counter: isCounter,
+		}
+
+		if (typeof executionOptions === "string") {
+			options.executionProfile = executionOptions
+		} else if (
+			executionOptions !== null &&
+			executionOptions !== undefined
+		) {
+			options.executionProfile = executionOptions.executionProfile
+			options.timestamp = executionOptions.timestamp
+			options.logged = executionOptions.logged !== false
+
+			if (executionOptions.isIdempotent !== undefined) {
+				options.isIdempotent = executionOptions.isIdempotent
+			}
+		}
+		return options
+	}
+}
+
+export default DocInfoAdapter

package/driver/mapping/index.d.ts

@@ -0,0 +1,219 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { types } from "../types"
+import { Client } from ".."
+import Long = types.Long
+
+export namespace mapping {
+	interface TableMappings {
+		getColumnName(propName: string): string
+
+		getPropertyName(columnName: string): string
+
+		newObjectInstance(): any
+	}
+
+	class DefaultTableMappings implements TableMappings {
+		getColumnName(propName: string): string
+
+		getPropertyName(columnName: string): string
+
+		newObjectInstance(): any
+	}
+
+	class UnderscoreCqlToCamelCaseMappings implements TableMappings {
+		getColumnName(propName: string): string
+
+		getPropertyName(columnName: string): string
+
+		newObjectInstance(): any
+	}
+
+	interface Result<T = any> extends Iterator<T> {
+		wasApplied(): boolean
+
+		first(): T | null
+
+		forEach(
+			callback: (currentValue: T, index: number) => void,
+			thisArg?: any,
+		): void
+
+		toArray(): T[]
+	}
+
+	type MappingExecutionOptions = {
+		executionProfile?: string
+		isIdempotent?: boolean
+		logged?: boolean
+		timestamp?: number | Long
+		fetchSize?: number
+		pageState?: number
+	}
+
+	interface ModelTables {
+		name: string
+		isView: boolean
+	}
+
+	class Mapper {
+		constructor(client: Client, options?: MappingOptions)
+
+		batch(
+			items: ModelBatchItem[],
+			executionOptions?: string | MappingExecutionOptions,
+		): Promise<Result>
+
+		forModel<T = any>(name: string): ModelMapper<T>
+	}
+
+	type MappingOptions = {
+		models: { [key: string]: ModelOptions }
+	}
+
+	type FindDocInfo = {
+		fields?: string[]
+		orderBy?: { [key: string]: string }
+		limit?: number
+	}
+
+	type InsertDocInfo = {
+		fields?: string[]
+		ttl?: number
+		ifNotExists?: boolean
+	}
+
+	type UpdateDocInfo = {
+		fields?: string[]
+		ttl?: number
+		ifExists?: boolean
+		when?: { [key: string]: any }
+		orderBy?: { [key: string]: string }
+		limit?: number
+		deleteOnlyColumns?: boolean
+	}
+
+	type RemoveDocInfo = {
+		fields?: string[]
+		ttl?: number
+		ifExists?: boolean
+		when?: { [key: string]: any }
+		deleteOnlyColumns?: boolean
+	}
+
+	type ModelOptions = {
+		tables?: string[] | ModelTables[]
+		mappings?: TableMappings
+		columns?: { [key: string]: string | ModelColumnOptions }
+		keyspace?: string
+	}
+
+	type ModelColumnOptions = {
+		name: string
+		toModel?: (columnValue: any) => any
+		fromModel?: (modelValue: any) => any
+	}
+
+	interface ModelBatchItem {}
+
+	interface ModelBatchMapper {
+		insert(doc: any, docInfo?: InsertDocInfo): ModelBatchItem
+
+		remove(doc: any, docInfo?: RemoveDocInfo): ModelBatchItem
+
+		update(doc: any, docInfo?: UpdateDocInfo): ModelBatchItem
+	}
+
+	interface ModelMapper<T = any> {
+		name: string
+		batching: ModelBatchMapper
+
+		get(
+			doc: { [key: string]: any },
+			docInfo?: { fields?: string[] },
+			executionOptions?: string | MappingExecutionOptions,
+		): Promise<null | T>
+
+		find(
+			doc: { [key: string]: any },
+			docInfo?: FindDocInfo,
+			executionOptions?: string | MappingExecutionOptions,
+		): Promise<Result<T>>
+
+		findAll(
+			docInfo?: FindDocInfo,
+			executionOptions?: string | MappingExecutionOptions,
+		): Promise<Result<T>>
+
+		insert(
+			doc: { [key: string]: any },
+			docInfo?: InsertDocInfo,
+			executionOptions?: string | MappingExecutionOptions,
+		): Promise<Result<T>>
+
+		update(
+			doc: { [key: string]: any },
+			docInfo?: UpdateDocInfo,
+			executionOptions?: string | MappingExecutionOptions,
+		): Promise<Result<T>>
+
+		remove(
+			doc: { [key: string]: any },
+			docInfo?: RemoveDocInfo,
+			executionOptions?: string | MappingExecutionOptions,
+		): Promise<Result<T>>
+
+		mapWithQuery(
+			query: string,
+			paramsHandler: (doc: any) => any[],
+			executionOptions?: string | MappingExecutionOptions,
+		): (
+			doc: any,
+			executionOptions?: string | MappingExecutionOptions,
+		) => Promise<Result<T>>
+	}
+
+	namespace q {
+		interface QueryOperator {}
+
+		function in_(arr: any): QueryOperator
+
+		function gt(value: any): QueryOperator
+
+		function gte(value: any): QueryOperator
+
+		function lt(value: any): QueryOperator
+
+		function lte(value: any): QueryOperator
+
+		function notEq(value: any): QueryOperator
+
+		function and(condition1: any, condition2: any): QueryOperator
+
+		function incr(value: any): QueryOperator
+
+		function decr(value: any): QueryOperator
+
+		function append(value: any): QueryOperator
+
+		function prepend(value: any): QueryOperator
+
+		function remove(value: any): QueryOperator
+	}
+}

package/driver/mapping/index.js

@@ -0,0 +1,57 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Module containing classes and fields related to the Mapper.
+ * @module mapping
+ */
+
+import Mapper from "./mapper.js"
+import ModelMapper from "./model-mapper.js"
+import ModelBatchMapper from "./model-batch-mapper.js"
+import { ModelBatchItem } from "./model-batch-item.js"
+import Result from "./result.js"
+import {
+	TableMappings,
+	DefaultTableMappings,
+	UnderscoreCqlToCamelCaseMappings,
+} from "./table-mappings.js"
+import { q } from "./q.js"
+
+export {
+	Mapper,
+	ModelMapper,
+	ModelBatchMapper,
+	ModelBatchItem,
+	Result,
+	TableMappings,
+	DefaultTableMappings,
+	UnderscoreCqlToCamelCaseMappings,
+	q,
+}
+export default {
+	Mapper,
+	ModelMapper,
+	ModelBatchMapper,
+	ModelBatchItem,
+	Result,
+	TableMappings,
+	DefaultTableMappings,
+	UnderscoreCqlToCamelCaseMappings,
+	q,
+}

package/driver/mapping/mapper.js

@@ -0,0 +1,225 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import ModelMapper from "./model-mapper.js"
+import MappingHandler from "./mapping-handler.js"
+import DocInfoAdapter from "./doc-info-adapter.js"
+import errors from "../errors.js"
+import Result from "./result.js"
+import ResultMapper from "./result-mapper.js"
+import ModelMappingInfo from "./model-mapping-info.js"
+import { ModelBatchItem } from "./model-batch-item.js"
+
+/**
+ * Represents an object mapper for Apache Cassandra and DataStax Enterprise.
+ * @alias module:mapping~Mapper
+ * @example <caption>Creating a Mapper instance with some options for the model 'User'</caption>
+ * const mappingOptions = {
+ *   models: {
+ *     'User': {
+ *       tables: ['users'],
+ *       mappings: new UnderscoreCqlToCamelCaseMappings(),
+ *       columnNames: {
+ *         'userid': 'id'
+ *       }
+ *     }
+ *   }
+ * };
+ * const mapper = new Mapper(client, mappingOptions);
+ * @example <caption>Creating a Mapper instance with other possible options for a model</caption>
+ * const mappingOptions = {
+ *   models: {
+ *     'Video': {
+ *       tables: ['videos', 'user_videos', 'latest_videos', { name: 'my_videos_view', isView: true }],
+ *       mappings: new UnderscoreCqlToCamelCaseMappings(),
+ *       columnNames: {
+ *         'videoid': 'id'
+ *       },
+ *       keyspace: 'ks1'
+ *     }
+ *   }
+ * };
+ * const mapper = new Mapper(client, mappingOptions);
+ */
+class Mapper {
+	/**
+	 * Creates a new instance of Mapper.
+	 * @param {Client} client The Client instance to use to execute the queries and fetch the metadata.
+	 * @param {MappingOptions} [options] The [MappingOptions]{@link module:mapping~MappingOptions} containing the
+	 * information of the models and table mappings.
+	 */
+	constructor(client, options) {
+		if (!client) {
+			throw new Error("client must be defined")
+		}
+
+		/**
+		 * The Client instance used to create this Mapper instance.
+		 * @type {Client}
+		 */
+		this.client = client
+
+		this._modelMappingInfos = ModelMappingInfo.parse(
+			options,
+			client.keyspace,
+		)
+		this._modelMappers = new Map()
+	}
+
+	/**
+	 * Gets a [ModelMapper]{@link module:mapping~ModelMapper} that is able to map documents of a certain model into
+	 * CQL rows.
+	 * @param {String} name The name to identify the model. Note that the name is case-sensitive.
+	 * @returns {ModelMapper} A [ModelMapper]{@link module:mapping~ModelMapper} instance.
+	 */
+	forModel(name) {
+		let modelMapper = this._modelMappers.get(name)
+
+		if (modelMapper === undefined) {
+			let mappingInfo = this._modelMappingInfos.get(name)
+
+			if (mappingInfo === undefined) {
+				if (!this.client.keyspace) {
+					throw new Error(
+						`No mapping information found for model '${name}'. ` +
+							`Mapper is unable to create default mappings without setting the keyspace`,
+					)
+				}
+
+				mappingInfo = ModelMappingInfo.createDefault(
+					name,
+					this.client.keyspace,
+				)
+				this.client.log(
+					"info",
+					`Mapping information for model '${name}' not found, creating default mapping. ` +
+						`Keyspace: ${mappingInfo.keyspace}; Table: ${mappingInfo.tables[0].name}.`,
+				)
+			} else {
+				this.client.log(
+					"info",
+					`Creating model mapper for '${name}' using mapping information. Keyspace: ${
+						mappingInfo.keyspace
+					}; Table${mappingInfo.tables.length > 1 ? "s" : ""}: ${mappingInfo.tables.map(
+						(t) => t.name,
+					)}.`,
+				)
+			}
+
+			modelMapper = new ModelMapper(
+				name,
+				new MappingHandler(this.client, mappingInfo),
+			)
+			this._modelMappers.set(name, modelMapper)
+		}
+
+		return modelMapper
+	}
+
+	/**
+	 * Executes a batch of queries represented in the items.
+	 * @param {Array<ModelBatchItem>} items
+	 * @param {Object|String} [executionOptions] An object containing the options to be used for the requests
+	 * execution or a string representing the name of the execution profile.
+	 * @param {String} [executionOptions.executionProfile] The name of the execution profile.
+	 * @param {Boolean} [executionOptions.isIdempotent] Defines whether the query can be applied multiple times without
+	 * changing the result beyond the initial application.
+	 * <p>
+	 *   The mapper uses the generated queries to determine the default value. When an UPDATE is generated with a
+	 *   counter column or appending/prepending to a list column, the execution is marked as not idempotent.
+	 * </p>
+	 * <p>
+	 *   Additionally, the mapper uses the safest approach for queries with lightweight transactions (Compare and
+	 *   Set) by considering them as non-idempotent. Lightweight transactions at client level with transparent retries can
+	 *   break linearizability. If that is not an issue for your application, you can manually set this field to true.
+	 * </p>
+	 * @param {Boolean} [executionOptions.logged=true] Determines whether the batch should be written to the batchlog.
+	 * @param {Number|Long} [executionOptions.timestamp] The default timestamp for the query in microseconds from the
+	 * unix epoch (00:00:00, January 1st, 1970).
+	 * @returns {Promise<Result>} A Promise that resolves to a [Result]{@link module:mapping~Result}.
+	 */
+	batch(items, executionOptions) {
+		if (!Array.isArray(items) || !(items.length > 0)) {
+			return Promise.reject(
+				new errors.ArgumentError(
+					"First parameter items should be an Array with 1 or more ModelBatchItem instances",
+				),
+			)
+		}
+
+		const queries = []
+		let isIdempotent = true
+		let isCounter
+
+		return Promise.all(
+			items.map((item) => {
+				if (!(item instanceof ModelBatchItem)) {
+					return Promise.reject(
+						new Error(
+							"Batch items must be instances of ModelBatchItem, use modelMapper.batching object to create each item",
+						),
+					)
+				}
+
+				return item.pushQueries(queries).then((options) => {
+					// The batch is idempotent when all the queries contained are idempotent
+					isIdempotent = isIdempotent && options.isIdempotent
+
+					// Let it fail at server level when there is a mix of counter and normal mutations
+					isCounter = options.isCounter
+				})
+			}),
+		)
+			.then(() =>
+				this.client.batch(
+					queries,
+					DocInfoAdapter.adaptBatchOptions(
+						executionOptions,
+						isIdempotent,
+						isCounter,
+					),
+				),
+			)
+			.then((rs) => {
+				// Results should only be adapted when the batch contains LWT (single table)
+				const info = items[0].getMappingInfo()
+				return new Result(rs, info, ResultMapper.getMutationAdapter(rs))
+			})
+	}
+}
+
+/**
+ * Represents the mapping options.
+ * @typedef {Object} module:mapping~MappingOptions
+ * @property {Object<String, ModelOptions>} models An associative array containing the
+ * name of the model as key and the table and column information as value.
+ */
+
+/**
+ * Represents a set of options that applies to a certain model.
+ * @typedef {Object} module:mapping~ModelOptions
+ * @property {Array<String>|Array<{name, isView}>} tables An Array containing the name of the tables or An Array
+ * containing the name and isView property to describe the table.
+ * @property {TableMappings} mappings The TableMappings implementation instance that is used to convert from column
+ * names to property names and the other way around.
+ * @property {Object.<String, String>} [columnNames] An associative array containing the name of the columns and
+ * properties that doesn't follow the convention defined in the <code>TableMappings</code>.
+ * @property {String} [keyspace] The name of the keyspace. Only mandatory when the Client is not using a keyspace.
+ */
+
+export default Mapper