@ragestudio/scylla-odm 0.22.2 → 0.22.3

package/driver/execution-options.js

@@ -0,0 +1,612 @@
+/*
+ * 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 utils from "./utils.js"
+import types from "./types/index.js"
+import errors from "./errors.js"
+
+const proxyExecuteKey = "ProxyExecute"
+
+/**
+ * A base class that represents a wrapper around the user provided query options with getter methods and proper
+ * default values.
+ * <p>
+ *   Note that getter methods might return <code>undefined</code> when not set on the query options or default
+ *  {@link Client} options.
+ * </p>
+ */
+class ExecutionOptions {
+	/**
+	 * Creates a new instance of {@link ExecutionOptions}.
+	 */
+	constructor() {}
+
+	/**
+	 * Creates an empty instance, where all methods return undefined, used internally.
+	 * @ignore
+	 * @return {ExecutionOptions}
+	 */
+	static empty() {
+		return new ExecutionOptions()
+	}
+
+	/**
+	 * Determines if the stack trace before the query execution should be maintained.
+	 * @abstract
+	 * @returns {Boolean}
+	 */
+	getCaptureStackTrace() {}
+
+	/**
+	 * Gets the [Consistency level]{@link module:types~consistencies} to be used for the execution.
+	 * @abstract
+	 * @returns {Number}
+	 */
+	getConsistency() {}
+
+	/**
+	 * Key-value payload to be passed to the server. On the server side, implementations of QueryHandler can use
+	 * this data.
+	 * @abstract
+	 * @returns {Object}
+	 */
+	getCustomPayload() {}
+
+	/**
+	 * Gets the amount of rows to retrieve per page.
+	 * @abstract
+	 * @returns {Number}
+	 */
+	getFetchSize() {}
+
+	/**
+	 * When a fixed host is set on the query options and the query plan for the load-balancing policy is not used, it
+	 * gets the host that should handle the query.
+	 * @returns {Host}
+	 */
+	getFixedHost() {}
+
+	/**
+	 * Gets the type hints for parameters given in the query, ordered as for the parameters.
+	 * @abstract
+	 * @returns {Array|Array<Array>}
+	 */
+	getHints() {}
+
+	/**
+	 * Determines whether the driver must retrieve the following result pages automatically.
+	 * <p>
+	 *   This setting is only considered by the [Client#eachRow()]{@link Client#eachRow} method.
+	 * </p>
+	 * @abstract
+	 * @returns {Boolean}
+	 */
+	isAutoPage() {}
+
+	/**
+	 * Determines whether its a counter batch. Only valid for [Client#batch()]{@link Client#batch}, it will be ignored by
+	 * other methods.
+	 * @abstract
+	 * @returns {Boolean} A <code>Boolean</code> value, it can't be <code>undefined</code>.
+	 */
+	isBatchCounter() {}
+
+	/**
+	 * Determines whether the batch should be written to the batchlog. Only valid for
+	 * [Client#batch()]{@link Client#batch}, it will be ignored by other methods.
+	 * @abstract
+	 * @returns {Boolean} A <code>Boolean</code> value, it can't be <code>undefined</code>.
+	 */
+	isBatchLogged() {}
+
+	/**
+	 * Determines whether the query can be applied multiple times without changing the result beyond the initial
+	 * application.
+	 * @abstract
+	 * @returns {Boolean}
+	 */
+	isIdempotent() {}
+
+	/**
+	 * Determines whether the query must be prepared beforehand.
+	 * @abstract
+	 * @returns {Boolean} A <code>Boolean</code> value, it can't be <code>undefined</code>.
+	 */
+	isPrepared() {}
+
+	/**
+	 * Determines whether query tracing is enabled for the execution.
+	 * @abstract
+	 * @returns {Boolean}
+	 */
+	isQueryTracing() {}
+
+	/**
+	 * Gets the keyspace for the query when set at query options level.
+	 * <p>
+	 *   Note that this method will return <code>undefined</code> when the keyspace is not set at query options level.
+	 *   It will only return the keyspace name when the user provided a different keyspace than the current
+	 *   {@link Client} keyspace.
+	 * </p>
+	 * @abstract
+	 * @returns {String}
+	 */
+	getKeyspace() {}
+
+	/**
+	 * Gets the load balancing policy used for this execution.
+	 * @returns {LoadBalancingPolicy} A <code>LoadBalancingPolicy</code> instance, it can't be <code>undefined</code>.
+	 */
+	getLoadBalancingPolicy() {}
+
+	/**
+	 * Gets the Buffer representing the paging state.
+	 * @abstract
+	 * @returns {Buffer}
+	 */
+	getPageState() {}
+
+	/**
+	 * Internal method that gets the preferred host.
+	 * @abstract
+	 * @ignore
+	 */
+	getPreferredHost() {}
+
+	/**
+	 * Gets the query options as provided to the execution method without setting the default values.
+	 * @returns {QueryOptions}
+	 */
+	getRawQueryOptions() {}
+
+	/**
+	 * Gets the timeout in milliseconds to be used for the execution per coordinator.
+	 * <p>
+	 *   A value of <code>0</code> disables client side read timeout for the execution. Default: <code>undefined</code>.
+	 * </p>
+	 * @abstract
+	 * @returns {Number}
+	 */
+	getReadTimeout() {}
+
+	/**
+	 * Gets the [retry policy]{@link module:policies/retry} to be used.
+	 * @abstract
+	 * @returns {RetryPolicy} A <code>RetryPolicy</code> instance, it can't be <code>undefined</code>.
+	 */
+	getRetryPolicy() {}
+
+	/**
+	 * Internal method to obtain the row callback, for "by row" results.
+	 * @abstract
+	 * @ignore
+	 */
+	getRowCallback() {}
+
+	/**
+	 * Internal method to get or generate a timestamp for the request execution.
+	 * @ignore
+	 * @returns {object|null}
+	 */
+	getOrGenerateTimestamp() {}
+
+	/**
+	 * Gets the index of the parameters that are part of the partition key to determine the routing.
+	 * @abstract
+	 * @ignore
+	 * @returns {Array}
+	 */
+	getRoutingIndexes() {}
+
+	/**
+	 * Gets the partition key(s) to determine which coordinator should be used for the query.
+	 * @abstract
+	 * @returns {Buffer|Array<Buffer>}
+	 */
+	getRoutingKey() {}
+
+	/**
+	 * Gets the array of the parameters names that are part of the partition key to determine the
+	 * routing. Only valid for non-prepared requests.
+	 * @abstract
+	 * @ignore
+	 */
+	getRoutingNames() {}
+
+	/**
+	 * Gets the the consistency level to be used for the serial phase of conditional updates.
+	 * @abstract
+	 * @returns {Number}
+	 */
+	getSerialConsistency() {}
+
+	/**
+	 * Gets the provided timestamp for the execution in microseconds from the unix epoch (00:00:00, January 1st, 1970).
+	 * <p>When a timestamp generator is used, this method returns <code>undefined</code>.</p>
+	 * @abstract
+	 * @returns {number|object|undefined|null}
+	 */
+	getTimestamp() {}
+
+	/**
+	 * @param {Array} hints
+	 * @abstract
+	 * @ignore
+	 */
+	setHints(hints) {}
+
+	/**
+	 * Sets the keyspace for the execution.
+	 * @ignore
+	 * @abstract
+	 * @param {String} keyspace
+	 */
+	setKeyspace(keyspace) {}
+
+	/**
+	 * @abstract
+	 * @ignore
+	 */
+	setPageState() {}
+
+	/**
+	 * Internal method that sets the preferred host.
+	 * @abstract
+	 * @ignore
+	 */
+	setPreferredHost() {}
+
+	/**
+	 * Sets the index of the parameters that are part of the partition key to determine the routing.
+	 * @param {Array} routingIndexes
+	 * @abstract
+	 * @ignore
+	 */
+	setRoutingIndexes(routingIndexes) {}
+
+	/**
+	 * Sets the routing key.
+	 * @abstract
+	 * @ignore
+	 */
+	setRoutingKey(value) {}
+}
+
+/**
+ * Internal implementation of {@link ExecutionOptions} that uses the value from the client options and execution
+ * profile into account.
+ * @ignore
+ */
+class DefaultExecutionOptions extends ExecutionOptions {
+	/**
+	 * Creates a new instance of {@link ExecutionOptions}.
+	 * @param {QueryOptions} queryOptions
+	 * @param {Client} client
+	 * @param {Function|null} rowCallback
+	 */
+	constructor(queryOptions, client, rowCallback) {
+		super()
+
+		this._queryOptions = queryOptions
+		this._rowCallback = rowCallback
+		this._routingKey = this._queryOptions.routingKey
+		this._hints = this._queryOptions.hints
+		this._keyspace = this._queryOptions.keyspace
+		this._routingIndexes = this._queryOptions.routingIndexes
+		this._pageState =
+			typeof this._queryOptions.pageState === "string"
+				? utils.allocBufferFromString(
+						this._queryOptions.pageState,
+						"hex",
+					)
+				: this._queryOptions.pageState
+		this._preferredHost = null
+
+		this._client = client
+		this._defaultQueryOptions = client.options.queryOptions
+		this._profile = client.profileManager.getProfile(
+			this._queryOptions.executionProfile,
+		)
+
+		// Build a custom payload object designed for DSE-specific functionality
+		this._customPayload = DefaultExecutionOptions.createCustomPayload(
+			this._queryOptions,
+			this._defaultQueryOptions,
+		)
+
+		if (!this._profile) {
+			throw new errors.ArgumentError(
+				`Execution profile "${this._queryOptions.executionProfile}" not found`,
+			)
+		}
+	}
+
+	/**
+	 * Creates a payload for given user.
+	 * @param {QueryOptions} userOptions
+	 * @param {QueryOptions} defaultQueryOptions
+	 * @private
+	 */
+	static createCustomPayload(userOptions, defaultQueryOptions) {
+		let customPayload =
+			userOptions.customPayload || defaultQueryOptions.customPayload
+		const executeAs = userOptions.executeAs || defaultQueryOptions.executeAs
+
+		if (executeAs) {
+			if (!customPayload) {
+				customPayload = {}
+				customPayload[proxyExecuteKey] =
+					utils.allocBufferFromString(executeAs)
+			} else if (!customPayload[proxyExecuteKey]) {
+				// Avoid appending to the existing payload object
+				customPayload = utils.extend({}, customPayload)
+				customPayload[proxyExecuteKey] =
+					utils.allocBufferFromString(executeAs)
+			}
+		}
+
+		return customPayload
+	}
+
+	/**
+	 * Creates a new instance {@link ExecutionOptions}, based on the query options.
+	 * @param {QueryOptions|null} queryOptions
+	 * @param {Client} client
+	 * @param {Function|null} [rowCallback]
+	 * @ignore
+	 * @return {ExecutionOptions}
+	 */
+	static create(queryOptions, client, rowCallback) {
+		if (!queryOptions || typeof queryOptions === "function") {
+			// queryOptions can be null/undefined and could be of type function when is an optional parameter
+			queryOptions = utils.emptyObject
+		}
+		return new DefaultExecutionOptions(queryOptions, client, rowCallback)
+	}
+
+	getCaptureStackTrace() {
+		return ifUndefined(
+			this._queryOptions.captureStackTrace,
+			this._defaultQueryOptions.captureStackTrace,
+		)
+	}
+
+	getConsistency() {
+		return ifUndefined3(
+			this._queryOptions.consistency,
+			this._profile.consistency,
+			this._defaultQueryOptions.consistency,
+		)
+	}
+
+	getCustomPayload() {
+		return this._customPayload
+	}
+
+	getFetchSize() {
+		return ifUndefined(
+			this._queryOptions.fetchSize,
+			this._defaultQueryOptions.fetchSize,
+		)
+	}
+
+	getFixedHost() {
+		return this._queryOptions.host
+	}
+
+	getHints() {
+		return this._hints
+	}
+
+	isAutoPage() {
+		return ifUndefined(
+			this._queryOptions.autoPage,
+			this._defaultQueryOptions.autoPage,
+		)
+	}
+
+	isBatchCounter() {
+		return ifUndefined(this._queryOptions.counter, false)
+	}
+
+	isBatchLogged() {
+		return ifUndefined3(
+			this._queryOptions.logged,
+			this._defaultQueryOptions.logged,
+			true,
+		)
+	}
+
+	isIdempotent() {
+		return ifUndefined(
+			this._queryOptions.isIdempotent,
+			this._defaultQueryOptions.isIdempotent,
+		)
+	}
+
+	/**
+	 * Determines if the query execution must be prepared beforehand.
+	 * @return {Boolean}
+	 */
+	isPrepared() {
+		return ifUndefined(
+			this._queryOptions.prepare,
+			this._defaultQueryOptions.prepare,
+		)
+	}
+
+	isQueryTracing() {
+		return ifUndefined(
+			this._queryOptions.traceQuery,
+			this._defaultQueryOptions.traceQuery,
+		)
+	}
+
+	getKeyspace() {
+		return this._keyspace
+	}
+
+	getLoadBalancingPolicy() {
+		return this._profile.loadBalancing
+	}
+
+	getOrGenerateTimestamp() {
+		let result = this.getTimestamp()
+
+		if (result === undefined) {
+			const generator = this._client.options.policies.timestampGeneration
+
+			if (
+				types.protocolVersion.supportsTimestamp(
+					this._client.controlConnection.protocolVersion,
+				) &&
+				generator
+			) {
+				result = generator.next(this._client)
+			} else {
+				result = null
+			}
+		}
+
+		return typeof result === "number"
+			? types.Long.fromNumber(result)
+			: result
+	}
+
+	getPageState() {
+		return this._pageState
+	}
+
+	/**
+	 * Gets the profile defined by the user or the default profile
+	 * @internal
+	 * @ignore
+	 */
+	getProfile() {
+		return this._profile
+	}
+
+	getRawQueryOptions() {
+		return this._queryOptions
+	}
+
+	getReadTimeout() {
+		return ifUndefined3(
+			this._queryOptions.readTimeout,
+			this._profile.readTimeout,
+			this._client.options.socketOptions.readTimeout,
+		)
+	}
+
+	getRetryPolicy() {
+		return ifUndefined3(
+			this._queryOptions.retry,
+			this._profile.retry,
+			this._client.options.policies.retry,
+		)
+	}
+
+	getRoutingIndexes() {
+		return this._routingIndexes
+	}
+
+	getRoutingKey() {
+		return this._routingKey
+	}
+
+	getRoutingNames() {
+		return this._queryOptions.routingNames
+	}
+
+	/**
+	 * Internal method to obtain the row callback, for "by row" results.
+	 * @ignore
+	 */
+	getRowCallback() {
+		return this._rowCallback
+	}
+
+	getSerialConsistency() {
+		return ifUndefined3(
+			this._queryOptions.serialConsistency,
+			this._profile.serialConsistency,
+			this._defaultQueryOptions.serialConsistency,
+		)
+	}
+
+	getTimestamp() {
+		return this._queryOptions.timestamp
+	}
+
+	/**
+	 * Internal property to set the custom payload.
+	 * @ignore
+	 * @internal
+	 * @param {Object} payload
+	 */
+	setCustomPayload(payload) {
+		this._customPayload = payload
+	}
+
+	/**
+	 * @param {Array} hints
+	 */
+	setHints(hints) {
+		this._hints = hints
+	}
+
+	/**
+	 * @param {String} keyspace
+	 */
+	setKeyspace(keyspace) {
+		this._keyspace = keyspace
+	}
+
+	/**
+	 * @param {Buffer} pageState
+	 */
+	setPageState(pageState) {
+		this._pageState = pageState
+	}
+
+	/**
+	 * @param {Array} routingIndexes
+	 */
+	setRoutingIndexes(routingIndexes) {
+		this._routingIndexes = routingIndexes
+	}
+
+	setRoutingKey(value) {
+		this._routingKey = value
+	}
+}
+
+function ifUndefined(v1, v2) {
+	return v1 !== undefined ? v1 : v2
+}
+
+function ifUndefined3(v1, v2, v3) {
+	if (v1 !== undefined) {
+		return v1
+	}
+	return v2 !== undefined ? v2 : v3
+}
+
+export { ExecutionOptions, DefaultExecutionOptions, proxyExecuteKey }
+
+export default { ExecutionOptions, DefaultExecutionOptions, proxyExecuteKey }