@ragestudio/scylla-odm 0.1.0

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@ragestudio/scylla-odm",
+  "version": "0.1.0",
+  "description": "An ODM for ScyllaDB",
+  "license": "MIT",
+  "author": "RageStudio",
+  "type": "module",
+  "main": "src/index.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "cassandra-driver": "^4.8.0"
+  }
+}

package/src/cql_gen/create_table.ts

@@ -0,0 +1,66 @@
+import type Model from "../model"
+
+export default function (model: Model): string {
+	const desc = model.schema
+	const tableName = desc.table_name
+	const keyspace = model.driver.config.keyspace
+	const fields = desc.fields
+	const key = desc.keys
+	const clusteringOrder = desc.clustering_order
+
+	let columnsDef = ""
+
+	for (const fieldName in fields) {
+		const field = fields[fieldName]
+		const typeStr = typeof field === "string" ? field : (field as any)?.type
+
+		if (!typeStr) {
+			throw new Error(
+				`Invalid field type for "${fieldName}" in model "${tableName}"`,
+			)
+		}
+
+		columnsDef += `"${fieldName}" ${typeStr.toUpperCase()}, `
+	}
+
+	let pkDef = ""
+
+	if (typeof key === "string") {
+		pkDef = `"${key}"`
+	} else if (Array.isArray(key) && key.length > 0) {
+		const first = key[0]
+
+		if (Array.isArray(first)) {
+			pkDef = `(${first.map((k) => `"${k}"`).join(", ")})`
+		} else {
+			pkDef = `"${first}"`
+		}
+
+		for (let i = 1; i < key.length; i++) {
+			pkDef += `, "${key[i]}"`
+		}
+	} else {
+		throw new Error(
+			`Missing or invalid primary key in model "${tableName}"`,
+		)
+	}
+
+	let clusterClause = ""
+
+	if (clusteringOrder) {
+		let orderDef = ""
+
+		for (const col in clusteringOrder) {
+			if (orderDef !== "") {
+				orderDef += ", "
+			}
+
+			orderDef += `"${col}" ${(clusteringOrder[col] as string).toUpperCase()}`
+		}
+		if (orderDef !== "") {
+			clusterClause = ` WITH CLUSTERING ORDER BY (${orderDef})`
+		}
+	}
+
+	return `CREATE TABLE IF NOT EXISTS ${keyspace}.${tableName} (${columnsDef}PRIMARY KEY (${pkDef}))${clusterClause}`
+}

package/src/index.ts

@@ -0,0 +1,186 @@
+import type {
+	Client as T_CassandraClient,
+	ClientOptions as T_CassandraClientOptions,
+	mapping as T_CassandraMapping,
+} from "cassandra-driver"
+import type { ClientConfig } from "./types"
+
+//@ts-ignore
+import path from "node:path"
+//@ts-ignore
+import Cassandra from "cassandra-driver"
+import loadSchemas from "./utils/loadSchemas"
+import buildMapper from "./utils/buildMapper"
+
+import { Model } from "./model"
+import { InferDocument } from "./types"
+
+const DEFAULT_MAX_RETRIES = 3
+const DEFAULT_RETRY_DELAY = 1000
+const { SCYLLA_CONTACT_POINTS, SCYLLA_LOCAL_DATA_CENTER, SCYLLA_KEYSPACE } =
+	process.env
+
+export default class ScyllaClient {
+	constructor(config: ClientConfig = {}) {
+		this.config = {
+			modelsPath: path.resolve(__dirname, "../../db"),
+			contactPoints:
+				(config.contactPoints ?? SCYLLA_CONTACT_POINTS)
+					? SCYLLA_CONTACT_POINTS.split(",")
+					: ["127.0.0.1"],
+			localDataCenter:
+				config.localDataCenter ??
+				SCYLLA_LOCAL_DATA_CENTER ??
+				"datacenter1",
+			keyspace: config.keyspace ?? SCYLLA_KEYSPACE ?? "default",
+			port: 9042,
+			maxRetries: DEFAULT_MAX_RETRIES,
+			retryDelay: DEFAULT_RETRY_DELAY,
+			...config,
+		}
+
+		const clientOptions: T_CassandraClientOptions = {
+			contactPoints: this.config.contactPoints,
+			localDataCenter: this.config.localDataCenter,
+			keyspace: this.config.keyspace,
+			protocolOptions: {
+				port: this.config.port,
+			},
+		}
+
+		if (this.config.pooling) {
+			clientOptions.pooling = this.config.pooling
+		}
+
+		this.client = new Cassandra.Client(clientOptions)
+	}
+
+	config: ClientConfig
+	client: T_CassandraClient
+	mapper: T_CassandraMapping.Mapper
+	models: Map<string, Model<any>> = new Map()
+
+	async initialize(options: { sync?: boolean } = {}) {
+		let models: Model<any>[]
+
+		try {
+			models = await loadSchemas(this.config.modelsPath)
+		} catch (error) {
+			throw new Error(`Failed to load models: ${error.message}`)
+		}
+
+		models = models.filter((schema) => schema instanceof Model)
+
+		this.mapper = new Cassandra.mapping.Mapper(this.client, {
+			models: buildMapper(models),
+		})
+
+		for (let model of models) {
+			model._connect(this)
+
+			this.models.set(
+				model.name,
+				model as Model<InferDocument<typeof model.schema>>,
+			)
+
+			if (options?.sync === true) {
+				await model._sync()
+			}
+		}
+
+		console.log("Connecting to ScyllaDB")
+		await this.connectWithRetry()
+		console.log("ScyllaDB Connected")
+	}
+
+	private async connectWithRetry(): Promise<void> {
+		let lastError: Error | null = null
+
+		for (let attempt = 1; attempt <= this.config.maxRetries!; attempt++) {
+			try {
+				await this.client.connect()
+				return
+			} catch (error) {
+				lastError = error
+				console.warn(
+					`Connection attempt ${attempt} failed: ${error.message}`,
+				)
+
+				if (attempt < this.config.maxRetries!) {
+					console.log(`Retrying in ${this.config.retryDelay}ms...`)
+					await this.delay(this.config.retryDelay!)
+				}
+			}
+		}
+
+		throw new Error(
+			`Failed to connect to ScyllaDB after ${this.config.maxRetries} attempts: ${lastError?.message}`,
+		)
+	}
+
+	private delay(ms: number): Promise<void> {
+		return new Promise((resolve) => setTimeout(resolve, ms))
+	}
+
+	async shutdown(): Promise<void> {
+		try {
+			await this.client.shutdown()
+			console.log("ScyllaDB connection closed")
+		} catch (error) {
+			console.error("Error shutting down ScyllaDB connection:", error)
+			throw error
+		}
+	}
+
+	async executeWithRetry<T>(
+		operation: () => Promise<T>,
+		operationName: string = "operation",
+	): Promise<T> {
+		let lastError: Error | null = null
+
+		for (let attempt = 1; attempt <= this.config.maxRetries!; attempt++) {
+			try {
+				return await operation()
+			} catch (error) {
+				lastError = error
+
+				// check if error is retryable
+				if (
+					this.isRetryableError(error) &&
+					attempt < this.config.maxRetries!
+				) {
+					console.warn(
+						`Operation ${operationName} attempt ${attempt} failed: ${error.message}`,
+					)
+					console.log(`Retrying in ${this.config.retryDelay}ms...`)
+
+					await this.delay(this.config.retryDelay!)
+					continue
+				}
+
+				// if not retryable or last attempt, throw
+				throw error
+			}
+		}
+
+		throw new Error(
+			`Operation ${operationName} failed after ${this.config.maxRetries} attempts: ${lastError?.message}`,
+		)
+	}
+
+	private isRetryableError(error: any): boolean {
+		// retry on network errors, timeouts, and certain ScyllaDB errors
+		const retryableMessages = [
+			"timeout",
+			"connection",
+			"network",
+			"unavailable",
+			"overloaded",
+			"no hosts available",
+		]
+
+		const errorMessage = error.message?.toLowerCase() || ""
+
+		return retryableMessages.some((msg) => errorMessage.includes(msg))
+	}
+}

package/src/model/index.ts

@@ -0,0 +1,93 @@
+import ScyllaClient from ".."
+import { Result } from "../result"
+
+import fillDefaults from "../utils/fillDefaults"
+
+import { mapping } from "cassandra-driver/lib/mapping"
+import type { DocumentResult, Query, QueryOptions } from "../types"
+import type { Schema } from "../schema"
+
+import findOneOP from "../operations/findOne"
+import findOP from "../operations/find"
+import updateOP from "../operations/update"
+import deleteOP from "../operations/delete"
+import countAllOP from "../operations/countAll"
+
+import tableExistsOP from "../operations/tableExists"
+import syncOP from "../operations/sync"
+
+export class Model<TDoc = any> {
+	name: string
+	schema: Schema<any>
+	driver: ScyllaClient
+	mapper: mapping.ModelMapper
+
+	constructor(name: string, schema: Schema<any>) {
+		this.name = name
+		this.schema = schema
+
+		if (!Array.isArray(this.schema.keys)) {
+			throw new Error(`[${this.name}] model has missing "keys" array`)
+		}
+		if (!this.schema.table_name) {
+			throw new Error(`[${this.name}] model has missing "table_name"`)
+		}
+		if (!this.schema.fields || typeof this.schema.fields !== "object") {
+			throw new Error(
+				`[${this.name}] model has missing or invalid "fields"`,
+			)
+		}
+	}
+
+	create = (data: Partial<TDoc>) => this._wrap(data)
+
+	find: {
+		(
+			query: Query<TDoc>,
+			options: QueryOptions & { raw: true },
+		): Promise<TDoc[]>
+		(
+			query?: Query<TDoc>,
+			options?: QueryOptions,
+		): Promise<DocumentResult<TDoc>[]>
+	} = findOP.bind(this)
+
+	findOne: {
+		(
+			query: Query<TDoc>,
+			options: QueryOptions & { raw: true },
+		): Promise<TDoc>
+		(
+			query?: Query<TDoc>,
+			options?: QueryOptions,
+		): Promise<DocumentResult<TDoc>>
+	} = findOneOP.bind(this)
+
+	update: (query: Query<TDoc>) => Promise<DocumentResult<TDoc>> =
+		updateOP.bind(this)
+
+	delete: (query: Query<TDoc>) => Promise<mapping.Result> =
+		deleteOP.bind(this)
+
+	countAll: () => Promise<number> = countAllOP.bind(this)
+
+	_sync: typeof syncOP = syncOP.bind(this)
+	_tableExists: typeof tableExistsOP = tableExistsOP.bind(this)
+
+	_wrap(row: any): DocumentResult<TDoc> | null {
+		if (!row) {
+			return null
+		}
+
+		row = fillDefaults(this.schema, row)
+
+		return new Result<TDoc>(row, this) as DocumentResult<TDoc>
+	}
+
+	_connect(driver: ScyllaClient) {
+		this.driver = driver
+		this.mapper = driver.mapper.forModel(this.name)
+	}
+}
+
+export default Model

package/src/operations/countAll.ts

@@ -0,0 +1,18 @@
+import type Model from "../model"
+
+export default async function (this: Model, timeoutMs: number = 60000) {
+	const cql = `SELECT COUNT(1) FROM ${this.driver.config.keyspace}.${this.schema.table_name}`
+
+	const queryOptions = {
+		prepare: true,
+		readTimeout: timeoutMs,
+	}
+
+	const operation = async () => {
+		const result = await this.driver.client.execute(cql, [], queryOptions)
+
+		return result.rows[0].count.toNumber()
+	}
+
+	return this.driver.executeWithRetry(operation, `countAll on ${this.name}`)
+}

package/src/operations/delete.ts

@@ -0,0 +1,9 @@
+import type Model from "../model"
+
+export default async function (this: Model, query: any) {
+	const operation = async () => {
+		return await this.mapper.remove(query)
+	}
+
+	return this.driver.executeWithRetry(operation, `delete on ${this.name}`)
+}

package/src/operations/find.ts

@@ -0,0 +1,42 @@
+import type Model from "../model"
+import type { mapping } from "cassandra-driver/lib/mapping"
+import type { Query, QueryOptions } from "../types"
+import queryParser from "../utils/queryParser"
+
+export default async function findOP<TDoc>(
+	this: Model<TDoc>,
+	query: Query<TDoc> = {},
+	options?: QueryOptions,
+) {
+	const { $limit, $orderby, ...rest } = query
+
+	let parsedQuery = queryParser(this, rest)
+
+	const docInfo: mapping.FindDocInfo = {}
+
+	if ($limit !== undefined) {
+		if (typeof $limit !== "number" || $limit <= 0) {
+			throw new TypeError(
+				`{$limit} operator must be a number greater than 0`,
+			)
+		}
+		docInfo.limit = $limit
+	}
+
+	if ($orderby !== undefined) {
+		docInfo.orderBy = $orderby as Record<string, "asc" | "desc">
+	}
+
+	const operation = async () => {
+		const result = await this.mapper.find(parsedQuery, docInfo)
+		const rows = result.toArray()
+
+		if (options?.raw === true) {
+			return rows
+		}
+
+		return rows.map((row) => this._wrap(row))
+	}
+
+	return this.driver.executeWithRetry(operation, `find on ${this.name}`)
+}

package/src/operations/findOne.ts

@@ -0,0 +1,25 @@
+import type { QueryOptions } from "../types"
+import type Model from "../model"
+import queryParser from "../utils/queryParser"
+
+export default function (this: Model, query: any, options?: QueryOptions) {
+	query = queryParser(this, query)
+
+	const operation = async () => {
+		let result = await this.mapper.get(query)
+
+		if (!result) {
+			return null
+		}
+
+		result = this._wrap(result)
+
+		if (options?.raw === true) {
+			return result.toRaw()
+		}
+
+		return result
+	}
+
+	return this.driver.executeWithRetry(operation, `findOne on ${this.name}`)
+}

package/src/operations/sync.ts

@@ -0,0 +1,22 @@
+import type Model from "../model"
+import generateCreateTableCQL from "../cql_gen/create_table"
+
+export default async function syncOP(this: Model) {
+	const tableExists = await this._tableExists()
+
+	if (tableExists) {
+		return
+	}
+
+	try {
+		await this.driver.client.execute(generateCreateTableCQL(this))
+
+		console.log(`Table "${this.schema.table_name}" created successfully`)
+	} catch (error) {
+		console.error(
+			`Failed to create table "${this.schema.table_name}":`,
+			error,
+		)
+		throw error
+	}
+}

package/src/operations/tableExists.ts

@@ -0,0 +1,29 @@
+import type Model from "../model"
+
+export default async function (this: Model) {
+	const cql = `
+			SELECT table_name
+			FROM system_schema.tables
+			WHERE keyspace_name = ?
+			AND table_name = ?
+		`
+
+	try {
+		const result = await this.driver.client.execute(
+			cql,
+			[this.driver.config.keyspace, this.schema.table_name],
+			{
+				prepare: true,
+			},
+		)
+
+		return result.rows.length > 0
+	} catch (error) {
+		console.error(
+			`Failed to check if table "${this.schema.table_name}" exists:`,
+			error,
+		)
+
+		return false
+	}
+}

package/src/operations/update.ts

@@ -0,0 +1,24 @@
+import type Model from "../model"
+import fillDefaults from "../utils/fillDefaults"
+import typeChecker from "../utils/typeChecker"
+
+export default async function (this: Model, query: any) {
+	query = fillDefaults(this.schema, query)
+
+	typeChecker(this, query)
+
+	if (typeof query.__v !== "undefined") {
+		if (Number.isNaN(query.__v)) {
+			query.__v = 0
+		} else {
+			query.__v = query.__v + 1
+		}
+	}
+
+	const operation = async () => {
+		await this.mapper.update(query)
+		return this._wrap(query)
+	}
+
+	return this.driver.executeWithRetry(operation, `update on ${this.name}`)
+}

package/src/result/index.ts

@@ -0,0 +1,90 @@
+import type { Model } from "../model"
+import typeChecker from "../utils/typeChecker"
+
+export class Result<TDoc = any> {
+	constructor(data: TDoc, model: Model<TDoc>) {
+		if (data == null) {
+			throw new Error("Cannot create Result with null or undefined data")
+		}
+
+		if (typeof data !== "object" || Array.isArray(data)) {
+			throw new Error("Result data must be an object")
+		}
+
+		Object.assign(this, data)
+
+		Object.defineProperty(this, "_model", {
+			value: model,
+			enumerable: false,
+			writable: false,
+			configurable: false,
+		})
+	}
+
+	_model: Model<TDoc>
+
+	async save() {
+		try {
+			const data = this.toRaw()
+
+			typeChecker(this._model, data)
+
+			return await this._model.update(data as any)
+		} catch (error: any) {
+			throw new Error(`Failed to save result: ${error.message}`)
+		}
+	}
+
+	async delete() {
+		try {
+			return await this._model.delete(this.toRaw() as any)
+		} catch (error: any) {
+			throw new Error(`Failed to delete result: ${error.message}`)
+		}
+	}
+
+	toRaw(): TDoc {
+		const raw: any = {}
+
+		for (const key in this) {
+			if (key === "_model") continue
+
+			if (this.propertyIsEnumerable(key)) {
+				const value = (this as any)[key]
+
+				try {
+					JSON.stringify(value)
+					raw[key] = value
+				} catch (error) {
+					raw[key] = String(value)
+				}
+			}
+		}
+
+		return raw as TDoc
+	}
+
+	isValid(): boolean {
+		try {
+			typeChecker(this._model, this.toRaw())
+			return true
+		} catch {
+			return false
+		}
+	}
+
+	getChangedFields(original: Partial<TDoc>): (keyof TDoc)[] {
+		const current = this.toRaw() as Record<string, any>
+		const changed: (keyof TDoc)[] = []
+
+		for (const key in current) {
+			if (!(key in original) || current[key] !== (original as any)[key]) {
+				changed.push(key as keyof TDoc)
+			}
+		}
+
+		return changed
+	}
+}
+
+export default Result

package/src/schema/index.ts

@@ -0,0 +1,16 @@
+import { TableKeys } from "../types"
+
+export class Schema<T> {
+	public readonly table_name: string
+	public readonly clustering_order: any
+	public readonly keys: TableKeys
+	public readonly fields: T
+
+	constructor(params: any, fields: T) {
+		this.table_name = params.table_name
+		this.keys = params.keys
+		this.fields = fields
+	}
+}
+
+export default Schema

package/src/types.ts

@@ -0,0 +1,89 @@
+import Result from "./result"
+import { Schema } from "./schema"
+
+export type ClientConfig = {
+	modelsPath?: string
+	contactPoints?: string[]
+	localDataCenter?: string
+	keyspace?: string
+	port?: number
+	maxRetries?: number
+	retryDelay?: number
+	pooling?: {
+		coreConnectionsPerHost?: Record<string, number>
+		maxRequestsPerConnection?: number
+	}
+}
+
+export enum ColumnTypes {
+	Ascii = "ascii",
+	Bigint = "bigint",
+	Blob = "blob",
+	Boolean = "boolean",
+	Counter = "counter",
+	Date = "date",
+	Decimal = "decimal",
+	Double = "double",
+	Duration = "duration",
+	Float = "float",
+	Frozen = "frozen",
+	Inet = "inet",
+	Int = "int",
+	List = "list",
+	Map = "map",
+	Set = "set",
+	Smallint = "smallint",
+	Text = "text",
+	Time = "time",
+	Timestamp = "timestamp",
+	Timeuuid = "timeuuid",
+	Tinyint = "tinyint",
+	Tuple = "tuple",
+	Uuid = "uuid",
+	Varchar = "varchar",
+	Varint = "varint",
+}
+
+export type QueryOperators<TValue> = {
+	$eq?: TValue
+	$ne?: TValue
+	$in?: TValue[]
+	$gt?: TValue
+	$gte?: TValue
+	$lt?: TValue
+	$lte?: TValue
+}
+
+export type TableKeys = (string | TableKeys)[]
+
+export interface Column<T> {
+	type?: ColumnTypes | string
+	required?: boolean
+}
+
+export type InferRawData<T> = {
+	[K in keyof T as K extends `$${string}` ? never : K]: T[K] extends Column<
+		infer U
+	>
+		? U
+		: T[K]
+}
+
+export type InferDocument<S> =
+	S extends Schema<infer T> ? InferRawData<T> : never
+
+export type DocumentResult<TDoc> = Result<TDoc> & TDoc
+
+export type QueryOptions = {
+	raw?: boolean
+}
+
+export type OrderBy<TDoc> = { [K in keyof TDoc]?: "asc" | "desc" }
+
+export type Query<TDoc> = {
+	[K in keyof TDoc]?: TDoc[K] | QueryOperators<TDoc[K]>
+} & {
+	$and?: Query<TDoc>[]
+	$limit?: number
+	$orderby?: OrderBy<TDoc>
+}

package/src/utils/buildMapper.js

@@ -0,0 +1,10 @@
+export default (map) => {
+	return map.reduce((obj, { name, schema }) => {
+		return {
+			...obj,
+			[name]: {
+				tables: [schema.table_name],
+			},
+		}
+	}, {})
+}

package/src/utils/fillDefaults.ts

@@ -0,0 +1,30 @@
+export default function fillDefaults(schema: any, data: any) {
+	const defaults = schema.options?.defaults
+
+	if (!defaults || Object.keys(defaults).length === 0) {
+		return data
+	}
+
+	let needsDefaults = false
+
+	for (const key in defaults) {
+		if (data[key] == null) {
+			needsDefaults = true
+			break
+		}
+	}
+
+	if (!needsDefaults) {
+		return data
+	}
+
+	const result = Object.assign({}, data)
+
+	for (const key in defaults) {
+		if (result[key] == null) {
+			result[key] = defaults[key]
+		}
+	}
+
+	return result
+}

package/src/utils/loadSchemas.ts

@@ -0,0 +1,39 @@
+import fs from "node:fs"
+import path from "node:path"
+
+export default async (fromPath: string): Promise<any[]> => {
+	if (typeof fromPath !== "string") {
+		return []
+	}
+
+	if (!fs.existsSync(fromPath)) {
+		console.warn(
+			`Cannot load models from [${fromPath}] case this path does not exist`,
+		)
+		return []
+	}
+
+	let schemas = []
+
+	let files = await fs.promises.readdir(fromPath)
+
+	files = files.filter((file) => file.endsWith(".js") || file.endsWith(".ts"))
+
+	for await (const file of files) {
+		const name = file.replace(".js", "")
+		const file_path = path.join(fromPath, file)
+
+		try {
+			let mod = await import(file_path)
+
+			mod = mod.default
+
+			schemas.push(mod)
+		} catch (error) {
+			console.error(`Failed to load schema [${name}]:`, error)
+			continue
+		}
+	}
+
+	return schemas
+}

package/src/utils/queryParser.ts

@@ -0,0 +1,192 @@
+import type { Model } from "../model"
+
+// @ts-ignore
+import cassandra from "cassandra-driver"
+const { q } = cassandra.mapping
+
+const MAX_QUERY_DEPTH = 3
+const MAX_IN_ELEMENTS = 1000
+
+const VALID_OPERATORS = new Set([
+	"$eq",
+	"$ne",
+	"$gt",
+	"$gte",
+	"$lt",
+	"$lte",
+	"$in",
+])
+
+function requireNotNull(value: any, operator: string): void {
+	if (value === null || value === undefined) {
+		throw new Error(
+			`${operator} operator cannot compare with null or undefined`,
+		)
+	}
+}
+
+function buildOperator(operator: string, opValue: any): any {
+	if (!VALID_OPERATORS.has(operator)) {
+		throw new Error(`Invalid operator: ${operator}`)
+	}
+
+	switch (operator) {
+		case "$eq":
+			return opValue
+
+		case "$ne":
+			requireNotNull(opValue, "$ne")
+			return q.notEq(opValue)
+
+		case "$in":
+			if (!Array.isArray(opValue)) {
+				throw new Error("$in operator requires an array")
+			}
+			if (opValue.length > MAX_IN_ELEMENTS) {
+				throw new Error(
+					`$in operator exceeds maximum of ${MAX_IN_ELEMENTS} elements`,
+				)
+			}
+			for (let i = 0; i < opValue.length; i++) {
+				if (opValue[i] === null || opValue[i] === undefined) {
+					throw new Error(
+						`$in array element at index ${i} cannot be null or undefined`,
+					)
+				}
+			}
+			return q.in_(opValue)
+
+		case "$gt":
+			requireNotNull(opValue, "$gt")
+			return q.gt(opValue)
+
+		case "$gte":
+			requireNotNull(opValue, "$gte")
+			return q.gte(opValue)
+
+		case "$lt":
+			requireNotNull(opValue, "$lt")
+			return q.lt(opValue)
+
+		case "$lte":
+			requireNotNull(opValue, "$lte")
+			return q.lte(opValue)
+	}
+}
+
+export default function queryParser(
+	model: Model<any>,
+	query: any,
+	depth: number = 0,
+) {
+	if (depth > MAX_QUERY_DEPTH) {
+		throw new Error(`Query depth exceeds maximum of ${MAX_QUERY_DEPTH}`)
+	}
+
+	if (!query || typeof query !== "object") {
+		return query
+	}
+
+	const parsedQuery: Record<string, any> = {}
+	const fields = model.schema.fields
+
+	for (const field of Object.keys(query)) {
+		const value = query[field]
+
+		if (field === "$and") {
+			handleAnd(model, value, parsedQuery, depth)
+			continue
+		}
+
+		if (field === "$or") {
+			throw new Error(
+				"ScyllaDB does not support OR queries across different columns. Use $in for a single column.",
+			)
+		}
+
+		if (!isValidFieldName(fields, field)) {
+			throw new Error(
+				`Invalid field name: [${field}] or it does not exist in schema`,
+			)
+		}
+
+		parsedQuery[field] = parseField(value)
+	}
+
+	return parsedQuery
+}
+
+function handleAnd(
+	model: Model<any>,
+	conditions: any,
+	parsedQuery: Record<string, any>,
+	depth: number,
+) {
+	if (!Array.isArray(conditions)) {
+		throw new Error("$and operator requires an array")
+	}
+	if (conditions.length > 10) {
+		throw new Error("$and operator exceeds maximum of 10 conditions")
+	}
+
+	for (let i = 0; i < conditions.length; i++) {
+		const condition = conditions[i]
+		if (!condition || typeof condition !== "object") {
+			throw new Error(`$and condition at index ${i} must be an object`)
+		}
+
+		const parsed = queryParser(model, condition, depth + 1)
+		for (const key of Object.keys(parsed)) {
+			if (key in parsedQuery) {
+				throw new Error(
+					`$and conflict: field "${key}" appears in multiple conditions`,
+				)
+			}
+		}
+		Object.assign(parsedQuery, parsed)
+	}
+}
+
+function parseField(value: any): any {
+	if (
+		value === null ||
+		typeof value !== "object" ||
+		Array.isArray(value) ||
+		value instanceof Date
+	) {
+		if (Array.isArray(value)) {
+			throw new Error(
+				"Array values require explicit operator (e.g., $in)",
+			)
+		}
+		return value
+	}
+
+	const operators = Object.keys(value)
+	const compiledOps = operators.map((op) => buildOperator(op, value[op]))
+
+	return compiledOps.length === 1
+		? compiledOps[0]
+		: (q.and as any)(...compiledOps)
+}
+
+export function isValidFieldName(
+	fields: Record<string, any>,
+	fieldName: string,
+): boolean {
+	const invalidPatterns = [
+		/^[0-9]/,
+		/[^a-zA-Z0-9_]/,
+		/^(select|insert|update|delete|drop|create|alter|truncate)$/i,
+	]
+
+	for (const pattern of invalidPatterns) {
+		if (pattern.test(fieldName)) return false
+	}
+
+	return fieldName in fields
+}
+
+export function isValidOperator(operator: string): boolean {
+	return VALID_OPERATORS.has(operator)
+}

package/src/utils/typeChecker.ts

@@ -0,0 +1,100 @@
+// @ts-ignore
+import cassandra from "cassandra-driver"
+const { types } = cassandra
+import type { Model } from "../model"
+import { isValidFieldName } from "./queryParser"
+
+const stringTypes = new Set(["ascii", "text", "varchar", "inet"])
+const intTypes = new Set(["int", "smallint", "tinyint"])
+const floatTypes = new Set(["double", "float"])
+const longTypes = new Set(["bigint", "counter"])
+
+function isValidValue(value: any, expectedType: string): boolean {
+	if (value === null || value === undefined) return true
+
+	if (stringTypes.has(expectedType)) return typeof value === "string"
+	if (intTypes.has(expectedType)) return Number.isInteger(value)
+	if (floatTypes.has(expectedType)) return typeof value === "number"
+	if (longTypes.has(expectedType)) {
+		return (
+			typeof value === "bigint" ||
+			typeof value === "number" ||
+			value instanceof types.Long
+		)
+	}
+
+	switch (expectedType) {
+		case "boolean":
+			return typeof value === "boolean"
+		case "decimal":
+			return (
+				typeof value === "number" ||
+				typeof value === "string" ||
+				value instanceof types.BigDecimal
+			)
+		case "varint":
+			return (
+				typeof value === "bigint" ||
+				typeof value === "number" ||
+				value instanceof types.Integer
+			)
+		case "timestamp":
+			return (
+				value instanceof Date ||
+				typeof value === "number" ||
+				typeof value === "string"
+			)
+		case "date":
+			return typeof value === "string" || value instanceof types.LocalDate
+		case "time":
+			return typeof value === "string" || value instanceof types.LocalTime
+		case "uuid":
+			return typeof value === "string" || value instanceof types.Uuid
+		case "timeuuid":
+			return typeof value === "string" || value instanceof types.TimeUuid
+		case "blob":
+			return Buffer.isBuffer(value) || value instanceof Uint8Array
+	}
+
+	if (expectedType.startsWith("list<") || expectedType.startsWith("set<")) {
+		return Array.isArray(value) || value instanceof Set
+	}
+	if (expectedType.startsWith("map<")) {
+		return (
+			typeof value === "object" && !Array.isArray(value) && value !== null
+		)
+	}
+
+	return false
+}
+
+export default function typeChecker(model: Model<any>, data: any): boolean {
+	if (!data || typeof data !== "object" || Array.isArray(data)) {
+		throw new TypeError(
+			`[${model.name}] Validation error: Data payload must be an object`,
+		)
+	}
+
+	const fields = model.schema.fields
+
+	for (const [key, value] of Object.entries(data)) {
+		if (!isValidFieldName(fields, key)) {
+			throw new Error(
+				`[${model.name}] Validation error: Field '${key}' does not exist in schema`,
+			)
+		}
+
+		const fieldConfig = fields[key]
+		const expectedType = (fieldConfig.type || "text").toLowerCase()
+
+		if (!isValidValue(value, expectedType)) {
+			const receivedType = Array.isArray(value) ? "array" : typeof value
+			throw new TypeError(
+				`[${model.name}] Validation error: Invalid type for field '${key}'. ` +
+					`Expected[${expectedType}], but received [${receivedType}]`,
+			)
+		}
+	}
+
+	return true
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "allowSyntheticDefaultImports": true,
+    "target": "ES2023",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "declaration": true,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "strict": false,
+    "noImplicitAny": false,
+    "skipLibCheck": true,
+    "preserveConstEnums": true,
+    "sourceMap": true,
+    "baseUrl": ".",
+  },
+  "include": ["**/*.ts"],
+}