@ragestudio/scylla-odm 0.22.2 → 0.22.4

package/driver/index.d.ts

@@ -0,0 +1,387 @@
+/*
+ * 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 * as events from "events"
+import * as tls from "tls"
+import { URL } from "url"
+import { auth } from "./auth"
+import { policies } from "./policies"
+import { types } from "./types"
+import { metadata } from "./metadata"
+import Long = types.Long
+import Uuid = types.Uuid
+
+// Export imported submodules
+export { concurrent } from "./concurrent"
+export { mapping } from "./mapping"
+export { auth, metadata, policies, types }
+
+export const version: number
+
+export function defaultOptions(): ClientOptions
+
+export type ValueCallback<T> = (err: Error, val: T) => void
+export type EmptyCallback = (err: Error) => void
+export type ArrayOrObject = any[] | { [key: string]: any }
+
+export class Client extends events.EventEmitter {
+	hosts: HostMap
+	keyspace: string
+	metadata: metadata.Metadata
+	metrics: null
+
+	constructor(options: ClientOptions)
+
+	connect(): Promise<void>
+
+	connect(callback: EmptyCallback): void
+
+	execute(
+		query: string,
+		params?: ArrayOrObject,
+		options?: QueryOptions,
+	): Promise<types.ResultSet>
+
+	execute(
+		query: string,
+		params: ArrayOrObject,
+		options: QueryOptions,
+		callback: ValueCallback<types.ResultSet>,
+	): void
+
+	execute(
+		query: string,
+		params: ArrayOrObject,
+		callback: ValueCallback<types.ResultSet>,
+	): void
+
+	execute(query: string, callback: ValueCallback<types.ResultSet>): void
+
+	eachRow(
+		query: string,
+		params: ArrayOrObject,
+		options: QueryOptions,
+		rowCallback: (n: number, row: types.Row) => void,
+		callback?: ValueCallback<types.ResultSet>,
+	): void
+
+	eachRow(
+		query: string,
+		params: ArrayOrObject,
+		rowCallback: (n: number, row: types.Row) => void,
+		callback?: ValueCallback<types.ResultSet>,
+	): void
+
+	eachRow(
+		query: string,
+		rowCallback: (n: number, row: types.Row) => void,
+	): void
+
+	stream(
+		query: string,
+		params?: ArrayOrObject,
+		options?: QueryOptions,
+		callback?: EmptyCallback,
+	): events.EventEmitter
+
+	batch(
+		queries: Array<string | { query: string; params?: ArrayOrObject }>,
+		options?: QueryOptions,
+	): Promise<types.ResultSet>
+
+	batch(
+		queries: Array<string | { query: string; params?: ArrayOrObject }>,
+		options: QueryOptions,
+		callback: ValueCallback<types.ResultSet>,
+	): void
+
+	batch(
+		queries: Array<string | { query: string; params?: ArrayOrObject }>,
+		callback: ValueCallback<types.ResultSet>,
+	): void
+
+	shutdown(): Promise<void>
+
+	shutdown(callback: EmptyCallback): void
+
+	getReplicas(keyspace: string, token: Buffer): Host[]
+
+	getState(): metadata.ClientState
+}
+
+export interface HostMap extends events.EventEmitter {
+	length: number
+
+	forEach(callback: (value: Host, key: string) => void): void
+
+	get(key: string): Host
+
+	keys(): string[]
+
+	values(): Host[]
+}
+
+export interface Host extends events.EventEmitter {
+	address: string
+	cassandraVersion: string
+	datacenter: string
+	rack: string
+	tokens: string[]
+	hostId: types.Uuid
+
+	canBeConsideredAsUp(): boolean
+
+	getCassandraVersion(): number[]
+
+	isUp(): boolean
+}
+
+export interface ExecutionOptions {
+	getCaptureStackTrace(): boolean
+
+	getConsistency(): types.consistencies
+
+	getCustomPayload(): { [key: string]: any }
+
+	getFetchSize(): number
+
+	getFixedHost(): Host
+
+	getHints(): string[] | string[][]
+
+	isAutoPage(): boolean
+
+	isBatchCounter(): boolean
+
+	isBatchLogged(): boolean
+
+	isIdempotent(): boolean
+
+	isPrepared(): boolean
+
+	isQueryTracing(): boolean
+
+	getKeyspace(): string
+
+	getLoadBalancingPolicy(): policies.loadBalancing.LoadBalancingPolicy
+
+	getPageState(): Buffer
+
+	getRawQueryOptions(): QueryOptions
+
+	getReadTimeout(): number
+
+	getRetryPolicy(): policies.retry.RetryPolicy
+
+	getRoutingKey(): Buffer | Buffer[]
+
+	getSerialConsistency(): types.consistencies
+
+	getTimestamp(): number | Long | undefined | null
+
+	setHints(hints: string[]): void
+}
+
+export interface ClientOptions {
+	contactPoints?: string[]
+	localDataCenter?: string
+	keyspace?: string
+	authProvider?: auth.AuthProvider
+	credentials?: {
+		username: string
+		password: string
+	}
+	encoding?: {
+		map?: Function
+		set?: Function
+		copyBuffer?: boolean
+		useUndefinedAsUnset?: boolean
+		useBigIntAsLong?: boolean
+		useBigIntAsVarint?: boolean
+	}
+	isMetadataSyncEnabled?: boolean
+	maxPrepared?: number
+	policies?: {
+		addressResolution?: policies.addressResolution.AddressTranslator
+		loadBalancing?: policies.loadBalancing.LoadBalancingPolicy
+		reconnection?: policies.reconnection.ReconnectionPolicy
+		retry?: policies.retry.RetryPolicy
+		speculativeExecution?: policies.speculativeExecution.SpeculativeExecutionPolicy
+		timestampGeneration?: policies.timestampGeneration.TimestampGenerator
+	}
+	pooling?: {
+		coreConnectionsPerHost?: { [key: number]: number }
+		heartBeatInterval?: number
+		maxRequestsPerConnection?: number
+		warmup?: boolean
+	}
+	prepareOnAllHosts?: boolean
+	profiles?: ExecutionProfile[]
+	protocolOptions?: {
+		maxSchemaAgreementWaitSeconds?: number
+		maxVersion?: number
+		noCompact?: boolean
+		port?: number
+	}
+	promiseFactory?: (
+		handler: (callback: (err: Error, result?: any) => void) => void,
+	) => Promise<any>
+	queryOptions?: QueryOptions
+	refreshSchemaDelay?: number
+	rePrepareOnUp?: boolean
+	socketOptions?: {
+		coalescingThreshold?: number
+		connectTimeout?: number
+		defunctReadTimeoutThreshold?: number
+		keepAlive?: boolean
+		keepAliveDelay?: number
+		readTimeout?: number
+		tcpNoDelay?: boolean
+	}
+	sslOptions?: tls.ConnectionOptions
+}
+
+export interface QueryOptions {
+	autoPage?: boolean
+	captureStackTrace?: boolean
+	consistency?: number
+	counter?: boolean
+	customPayload?: any
+	executionProfile?: string | ExecutionProfile
+	fetchSize?: number
+	hints?: string[] | string[][]
+	host?: Host
+	isIdempotent?: boolean
+	keyspace?: string
+	logged?: boolean
+	pageState?: Buffer | string
+	prepare?: boolean
+	readTimeout?: number
+	retry?: policies.retry.RetryPolicy
+	routingIndexes?: number[]
+	routingKey?: Buffer | Buffer[]
+	routingNames?: string[]
+	serialConsistency?: number
+	timestamp?: number | Long
+	traceQuery?: boolean
+}
+
+export class ExecutionProfile {
+	consistency?: types.consistencies
+	loadBalancing?: policies.loadBalancing.LoadBalancingPolicy
+	name: string
+	readTimeout?: number
+	retry?: policies.retry.RetryPolicy
+	serialConsistency?: types.consistencies
+
+	constructor(
+		name: string,
+		options: {
+			consistency?: types.consistencies
+			loadBalancing?: policies.loadBalancing.LoadBalancingPolicy
+			readTimeout?: number
+			retry?: policies.retry.RetryPolicy
+			serialConsistency?: types.consistencies
+		},
+	)
+}
+
+export namespace errors {
+	class ArgumentError extends DriverError {
+		constructor(message: string)
+	}
+
+	class AuthenticationError extends DriverError {
+		constructor(message: string)
+	}
+
+	class BusyConnectionError extends DriverError {
+		constructor(
+			address: string,
+			maxRequestsPerConnection: number,
+			connectionLength: number,
+		)
+	}
+
+	class VIntOutOfRangeException extends DriverError {
+		constructor(long: Long)
+	}
+
+	abstract class DriverError extends Error {
+		info: string
+
+		constructor(message: string, constructor?: any)
+	}
+
+	class DriverInternalError extends DriverError {
+		constructor(message: string)
+	}
+
+	class NoHostAvailableError extends DriverError {
+		innerErrors: any
+
+		constructor(innerErrors: any, message?: string)
+	}
+
+	class NotSupportedError extends DriverError {
+		constructor(message: string)
+	}
+
+	class OperationTimedOutError extends DriverError {
+		host?: string
+
+		constructor(message: string, host?: string)
+	}
+
+	class ResponseError extends DriverError {
+		code: number
+
+		constructor(code: number, message: string)
+	}
+}
+
+export namespace token {
+	interface Token {
+		compare(other: Token): number
+
+		equals(other: Token): boolean
+
+		getType(): { code: types.dataTypes; info: any }
+
+		getValue(): any
+	}
+
+	interface TokenRange {
+		start: Token
+		end: Token
+
+		compare(other: TokenRange): number
+
+		contains(token: Token): boolean
+
+		equals(other: TokenRange): boolean
+
+		isEmpty(): boolean
+
+		isWrappedAround(): boolean
+
+		splitEvenly(numberOfSplits: number): TokenRange[]
+
+		unwrap(): TokenRange[]
+	}
+}

package/driver/index.js

@@ -0,0 +1,81 @@
+/*
+ * 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 clientOptions from "./client-options.js"
+import Client from "./client.js"
+import { ExecutionProfile } from "./execution-profile.js"
+import { ExecutionOptions } from "./execution-options.js"
+import types from "./types/index.js"
+import errors from "./errors.js"
+import policies from "./policies/index.js"
+import auth from "./auth/index.js"
+import mapping from "./mapping/index.js"
+import concurrent from "./concurrent/index.js"
+import { Token, TokenRange } from "./token.js"
+import Metadata from "./metadata/index.js"
+import Encoder from "./encoder.js"
+import { version as pkgVersion } from "../../package.json" with { type: "json" }
+
+export {
+	Client,
+	ExecutionProfile,
+	ExecutionOptions,
+	types,
+	errors,
+	policies,
+	auth,
+	mapping,
+	concurrent,
+	Encoder,
+}
+
+export const token = {
+	Token: Token,
+	TokenRange: TokenRange,
+}
+
+export const metadata = {
+	Metadata: Metadata,
+}
+
+/**
+ * Returns a new instance of the default [options]{@link ClientOptions} used by the driver.
+ */
+export function defaultOptions() {
+	return clientOptions.defaultOptions()
+}
+
+export const version = pkgVersion
+
+const _default = {
+	Client,
+	ExecutionProfile,
+	ExecutionOptions,
+	types,
+	errors,
+	policies,
+	auth,
+	mapping,
+	concurrent,
+	token,
+	metadata,
+	Encoder,
+	defaultOptions,
+	version,
+}
+
+export default _default

package/driver/mapping/cache.js

@@ -0,0 +1,214 @@
+/*
+ * 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 { QueryOperator, QueryAssignment } from "./q.js"
+
+/**
+ * Provides utility methods for obtaining a caching keys based on the specifics of the Mapper methods.
+ * @ignore
+ */
+class Cache {
+	/**
+	 * Gets an iterator of keys to uniquely identify a document shape for a select query.
+	 * @param {Array<String>} docKeys
+	 * @param {Object} doc
+	 * @param {{fields, limit, orderBy}} docInfo
+	 * @returns {Iterator}
+	 */
+	static *getSelectKey(docKeys, doc, docInfo) {
+		yield* Cache._yieldKeyAndOperators(docKeys, doc)
+
+		yield* Cache._getSelectDocInfo(docInfo)
+	}
+	/**
+	 * Gets an iterator of keys to uniquely identify a shape for a select all query.
+	 * @param {{fields, limit, orderBy}} docInfo
+	 * @returns {Iterator}
+	 */
+	static *getSelectAllKey(docInfo) {
+		yield "root"
+
+		yield* Cache._getSelectDocInfo(docInfo)
+	}
+
+	/**
+	 * Gets the parts of the key for a select query related to the docInfo.
+	 * @param {{fields, limit, orderBy}} docInfo
+	 * @private
+	 */
+	static *_getSelectDocInfo(docInfo) {
+		if (docInfo) {
+			if (docInfo.fields && docInfo.fields.length > 0) {
+				// Use a separator from properties
+				yield "|f|"
+				yield* docInfo.fields
+			}
+
+			if (typeof docInfo.limit === "number") {
+				yield "|l|"
+			}
+
+			if (docInfo.orderBy) {
+				yield "|o|"
+
+				// orderBy is uses property names as keys and 'asc'/'desc' as values
+				const keys = Object.keys(docInfo.orderBy)
+				for (let i = 0; i < keys.length; i++) {
+					const key = keys[i]
+					yield key
+					yield docInfo.orderBy[key]
+				}
+			}
+		}
+	}
+
+	/**
+	 * Gets an iterator of keys to uniquely identify a document shape for an insert query.
+	 * @param {Array<String>} docKeys
+	 * @param {{ifNotExists, ttl, fields}} docInfo
+	 * @returns {Iterator}
+	 */
+	static *getInsertKey(docKeys, docInfo) {
+		// No operator supported on INSERT values
+		yield* docKeys
+
+		if (docInfo) {
+			if (docInfo.fields && docInfo.fields.length > 0) {
+				// Use a separator from properties
+				yield "|f|"
+				yield* docInfo.fields
+			}
+
+			if (typeof docInfo.ttl === "number") {
+				yield "|t|"
+			}
+
+			if (docInfo.ifNotExists) {
+				yield "|e|"
+			}
+		}
+	}
+
+	/**
+	 * Gets an iterator of keys to uniquely identify a document shape for an UPDATE query.
+	 * @param {Array<String>} docKeys
+	 * @param {Object} doc
+	 * @param {{ifExists, when, ttl, fields}} docInfo
+	 */
+	static *getUpdateKey(docKeys, doc, docInfo) {
+		yield* Cache._yieldKeyAndAllQs(docKeys, doc)
+
+		if (docInfo) {
+			if (docInfo.fields && docInfo.fields.length > 0) {
+				// Use a separator from properties
+				yield "|f|"
+				yield* docInfo.fields
+			}
+
+			if (typeof docInfo.ttl === "number") {
+				yield "|t|"
+			}
+
+			if (docInfo.ifExists) {
+				yield "|e|"
+			}
+
+			if (docInfo.when) {
+				yield* Cache._yieldKeyAndOperators(
+					Object.keys(docInfo.when),
+					docInfo.when,
+				)
+			}
+		}
+	}
+
+	/**
+	 * Gets an iterator of keys to uniquely identify a document shape for a DELETE query.
+	 * @param {Array<String>} docKeys
+	 * @param {Object} doc
+	 * @param {{ifExists, when, fields, deleteOnlyColumns}} docInfo
+	 * @returns {Iterator}
+	 */
+	static *getRemoveKey(docKeys, doc, docInfo) {
+		yield* Cache._yieldKeyAndOperators(docKeys, doc)
+
+		if (docInfo) {
+			if (docInfo.fields && docInfo.fields.length > 0) {
+				// Use a separator from properties
+				yield "|f|"
+				yield* docInfo.fields
+			}
+
+			if (docInfo.ifExists) {
+				yield "|e|"
+			}
+
+			if (docInfo.deleteOnlyColumns) {
+				yield "|dc|"
+			}
+
+			if (docInfo.when) {
+				yield* Cache._yieldKeyAndOperators(
+					Object.keys(docInfo.when),
+					docInfo.when,
+				)
+			}
+		}
+	}
+
+	static *_yieldKeyAndOperators(keys, obj) {
+		for (let i = 0; i < keys.length; i++) {
+			const key = keys[i]
+			yield key
+			yield* Cache._yieldOperators(obj[key])
+		}
+	}
+
+	static *_yieldOperators(value) {
+		if (
+			value !== null &&
+			value !== undefined &&
+			value instanceof QueryOperator
+		) {
+			yield value.key
+			if (value.hasChildValues) {
+				yield* Cache._yieldOperators(value.value[0])
+				yield "|/|"
+				yield* Cache._yieldOperators(value.value[1])
+			}
+		}
+	}
+
+	static *_yieldKeyAndAllQs(keys, obj) {
+		for (let i = 0; i < keys.length; i++) {
+			const key = keys[i]
+			yield key
+			const value = obj[key]
+			if (value !== null && value !== undefined) {
+				if (value instanceof QueryOperator) {
+					yield* Cache._yieldOperators(value)
+				} else if (value instanceof QueryAssignment) {
+					yield value.sign
+					yield value.inverted
+				}
+			}
+		}
+	}
+}
+
+export default Cache