cassandra-core

A lightweight, high-performance TypeScript library for Apache Cassandra built on top of the official cassandra-driver.

Unlike a traditional ORM, Cassandra provides a minimal abstraction layer that helps you build CQL statements, execute queries, perform batch operations, map database rows to TypeScript objects, and integrate seamlessly with sql-core's CRUDRepository.

The library is designed for developers who prefer explicit CQL while reducing repetitive boilerplate.

Features

• Lightweight wrapper around the official cassandra-driver
• High-performance query execution
• Metadata-driven object mapping
• Insert statement builder
• Batch insert builder
• Batch execution
• Object-to-column mapping
• Boolean value conversion
• Default value support
• Query helpers
• Scalar queries
• Count queries
• Repository integration with sql-core
• No decorators
• No runtime reflection
• Minimal overhead

Installation

npm install cassandra-driver cassandra-core

Why cassandra-core?

Most Cassandra libraries fall into one of two categories:

• Very low-level driver APIs
• Heavy ORM frameworks

This library sits between them.

It keeps the flexibility of handwritten CQL while providing convenient utilities for:

• CRUD operations
• Object mapping
• Batch execution
• Repository integration

The result is a clean, predictable API with almost zero runtime overhead.

Architecture

    Application
         │
         ▼
  CRUDRepository (sql-core)
         │
         ▼
      Executor
         │
         ▼
Cassandra ClientManager
         │
         ▼
  cassandra-driver
         │
         ▼
  Apache Cassandra

The library can be used directly or integrated with sql-core.

Integration with sql-core and query-mappers

This library is designed to work seamlessly with the sql-core ecosystem while providing Cassandra-native query capabilities.

sql-core

Although Apache Cassandra uses CQL instead of SQL, this library integrates with sql-core by implementing its execution abstraction. This allows applications to reuse generic repository components such as:

• CRUDRepository
• Repository abstractions
• Statement execution
• Common data access patterns

The CRUD infrastructure remains database-agnostic, while this library handles Cassandra-specific execution.

query-mappers

This library also integrates with query-mappers to build dynamic Cassandra queries from search models.

Instead of writing CQL manually for every search operation, applications can define search models and let query-mappers generate query conditions. The Cassandra search layer then translates these conditions into efficient CQL while respecting Cassandra's query model and data-access best practices.

This provides:

• Dynamic search conditions
• Filter mapping
• Type-safe query construction
• Reusable search models
• Consistent query definitions across applications

Together, these libraries provide a complete development stack for Apache Cassandra:

  Application
       │
       ▼
 query-mappers
       │
       ▼
Cassandra Search
       │
       ▼
 CRUDRepository (sql-core)
       │
       ▼
   Executor
       │
       ▼
Cassandra Client
       │
       ▼
Apache Cassandra

Applications benefit from reusable CRUD repositories, dynamic search capabilities, and a lightweight execution layer without introducing a heavyweight ORM.

Getting Started

import { Client } from "cassandra-driver";
import { ClientManager } from "cassandra-core";

const client = new Client({
    contactPoints: ["127.0.0.1"],
    localDataCenter: "datacenter1",
    keyspace: "sample"
});

const db = new ClientManager(client);

Execute Commands

await db.execute(
    "INSERT INTO users(id,name) VALUES(?,?)",
    ["u001", "John"]
);

Query

const users = await db.query<User>(
    "SELECT * FROM users WHERE id=?",
    ["u001"]
);

Query One

const user = await db.queryOne<User>(
    "SELECT * FROM users WHERE id=?",
    ["u001"]
);

Execute Scalar

const count = await db.executeScalar<number>(
    "SELECT COUNT(*) FROM users"
);

Count

const total = await db.count(
    "SELECT COUNT(*) FROM users"
);

Metadata Mapping

Attributes describe how an object maps to Cassandra columns.

const attributes = {
    id: {
        key: true
    },
    fullName: {
        column: "full_name"
    },
    active: {
        type: "boolean",
        true: "Y",
        false: "N"
    },
    createdAt: {
        default: new Date()
    }
};

Supported features include:

• column mapping
• default values
• ignored fields
• version field
• boolean conversion
• key fields

Build Insert Statement

const statement = buildToInsert(
    user,
    "users",
    attributes
);

await db.execute(
    statement.query,
    statement.params
);

Generated CQL:

INSERT INTO users(id, full_name, active)
VALUES (?, ?, ?)

Batch Insert

const statements = buildToInsertBatch(
    users,
    "users",
    attributes
);

await db.executeBatch(statements);

Batch execution supports configurable batch sizes for large data imports.

Boolean Mapping

Boolean values can be mapped to custom database values.

active: {
    type: "boolean",
    true: "Y",
    false: "N"
}

or

active: {
    type: "boolean",
    true: 1,
    false: 0
}

This is useful when working with legacy schemas.

Column Mapping

Property names and column names do not need to match.

const attributes = {
    fullName: {
        column: "full_name"
    }
};

Default Values

Default values are automatically applied when the property is undefined.

createdDate: {
    default: new Date()
}

Batch Execution

Execute multiple statements efficiently.

await db.executeBatch(statements);

A batch size can be specified for large workloads.

await db.executeBatch(statements, 100);

Object Mapping

The library automatically supports:

• column mapping
• boolean conversion
• nullable fields
• TypeScript objects

without decorators or runtime reflection.

CRUD Support

This library provides metadata-driven builders for insert operations.

Combined with sql-core, applications can reuse the generic CRUDRepository while executing against Cassandra.

Search

Unlike relational databases, Cassandra has different query capabilities.

For this reason, Cassandra search is implemented separately instead of reusing the SQL search framework from sql-core.

This allows the library to generate efficient CQL while respecting Cassandra best practices.

Performance

The library is designed for high throughput.

Features include:

• prepared statements
• minimal object allocation
• no ORM tracking
• no decorators
• no reflection
• thin wrapper around the official driver

API

ClientManager

Provides:

• execute()
• executeBatch()
• query()
• queryOne()
• executeScalar()
• count()

Builders

• buildToInsert()
• buildToInsertBatch()

Metadata

• metadata()

Best Practices

• Use prepared statements whenever possible.
• Keep batch sizes reasonable.
• Model tables according to access patterns.
• Avoid unnecessary ALLOW FILTERING.
• Reuse ClientManager throughout the application.
• Integrate with CRUDRepository for reusable CRUD operations.

Ecosystem

This library is part of a modular TypeScript ecosystem. Each library has a focused responsibility and can be used independently or together.

| Library | Purpose | | ------------------- | ------------------------------------------------------------------------------------ | | sql-core | Generic CRUD repository framework and execution abstractions | | query-mappers | Dynamic query and search model mapping | | cassandra-core | Cassandra client, CQL builders, metadata mapping, search, and repository integration | | config-plus | Configuration management | | health-service | Health monitoring | | redis-messaging | Distributed messaging |

Using these libraries together provides a clean architecture where:

• sql-core supplies reusable CRUD infrastructure.
• query-mappers builds dynamic search conditions.
• cassandra-core executes Cassandra-specific CQL and implements Cassandra-native search behavior.

This separation keeps each library focused while allowing applications to share repository patterns and query models across projects.

Roadmap

Planned features include:

• Update builder
• Delete builder
• Search framework
• Paging helpers
• TTL support
• Lightweight transactions (IF EXISTS / IF NOT EXISTS)
• Repository helpers
• Health checker improvements

Contributing

Contributions, bug reports, and feature requests are welcome.

Please open an issue or submit a pull request.

GitHub Repository:

https://github.com/core-ts/cassandra

License

MIT