Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
initMappers
✓ import { initMappers } from 'cassandra-codegen';
✗ const { initMappers } = require('cassandra-codegen');
Initializes all generated mappers with a connected `cassandra-driver` client. Must be called once before using any mappers.
cyclistCategoryMapper
✓ import { cyclistCategoryMapper } from 'cassandra-codegen';
✗ import cyclistCategoryMapper from 'cassandra-codegen';
This represents a dynamically generated mapper for a specific Cassandra table (e.g., `cyclist_category`). While the README indicates importing directly from `cassandra-codegen`, in practice, this often implies the generated code is compiled or re-exported, or that the path points to the actual generated file output by the CLI tool (e.g., `./generated/mykeyspace`). Always confirm the exact import path based on your `cassandra-codegen` CLI output configuration.
queryOperator
✓ import { queryOperator } from 'cassandra-codegen';
✗ import * as queryOperator from 'cassandra-codegen/queryOperator';
Provides type-safe wrappers for `cassandra-driver`'s query operators (e.g., `gte`, `lte`), used within mapper queries.
This quickstart demonstrates how to set up `cassandra-codegen` in a TypeScript project: connecting a Cassandra client, initializing the generated mappers, and then performing basic `get` and `find` operations using a generated mapper and type-safe query operators.
import { initMappers, queryOperator } from 'cassandra-codegen';
import type { CyclistCategoryRow } from './generated/mykeyspace'; // Adjust path to your generated types
import { Client } from 'cassandra-driver';
// 1. Configure and connect your cassandra-driver client
const cassandraClient = new Client({
contactPoints: ['127.0.0.1'], // Your Cassandra host
localDataCenter: 'datacenter1', // Your datacenter
credentials: { username: 'user', password: 'password' }, // Your credentials
keyspace: 'mykeyspace', // The keyspace you generated types for
});
async function main() {
await cassandraClient.connect();
console.log('Cassandra client connected.');
// 2. Initialize the generated mappers with the connected client
await initMappers(cassandraClient);
console.log('Mappers initialized.');
// 3. Import and use a generated mapper (e.g., 'cyclistCategoryMapper')
// Assuming 'cyclistCategoryMapper' and 'CyclistCategoryRow' are exported from './generated/mykeyspace.ts'
// You must run the `cassandra-codegen` CLI tool first to generate these files.
const cyclistCategoryMapper: {
get: (criteria: { category: string; points: number }) => Promise<CyclistCategoryRow | null>;
find: (criteria: { category?: string; points?: number | { $gte?: number; $lte?: number } }) => Promise<CyclistCategoryRow[]>;
// ... other generated methods like insert, update, remove
} = {} as any; // Placeholder for actual generated mapper
console.log('\n--- Fetching a specific cyclist category ---');
const specificCyclist = await cyclistCategoryMapper.get({
category: 'GC',
points: 100,
});
console.log('Retrieved:', specificCyclist);
console.log('\n--- Finding cyclists using a query operator ---');
const filteredCyclists = await cyclistCategoryMapper.find({
category: 'GC',
points: queryOperator.gte(42), // Using a type-safe query operator
});
console.log('Filtered results:', filteredCyclists);
await cassandraClient.shutdown();
console.log('Cassandra client disconnected.');
}
main().catch(console.error);
/*
To run this example:
1. Ensure Cassandra is running and your keyspace/table exists.
2. Install dependencies: `npm install cassandra-codegen cassandra-driver @types/cassandra-driver`
3. Generate types/mappers: `npm exec cassandra-codegen -- --host 127.0.0.1 --port 9042 --datacenter datacenter1 --username user --password password --keyspace mykeyspace --generate-ts-file --output-dir ./generated`
4. Adjust the import path for `CyclistCategoryRow` and the mocked `cyclistCategoryMapper` to point to your generated file (e.g., `./generated/mykeyspace`).
5. Run with `ts-node your-file.ts` (if `ts-node` is installed) or compile and run `tsc your-file.ts && node your-file.js`.
*/
cassandra-codegen --version
Errors
Common errors & fixes
ReferenceError: Cannot access 'cyclistCategoryMapper' before initialization
The `initMappers` function was not called with a connected Cassandra client before attempting to use a generated mapper.
fixCall `await initMappers(yourConnectedCassandraClient);` once at application startup.
Error: All contact points failed to connect
The Cassandra host, port, datacenter, or credentials provided to the `cassandra-codegen` CLI or the `cassandra-driver` client are incorrect, or the Cassandra instance is not running/accessible.
fixVerify the `--host`, `--port`, `--datacenter`, `--username`, and `--password` arguments when running `cassandra-codegen`, and check your `cassandra-driver` client configuration. Ensure the Cassandra database is running and reachable from your application's environment.
Property 'mapColumn' does not exist on type 'CyclistCategoryRow'
This error can occur if your Cassandra table uses a `map` type column and you are using `cassandra-codegen` version older than 0.0.10/0.0.11, or the generated types are incorrect.
fixUpgrade `cassandra-codegen` to version 0.0.11 or newer. Re-run the code generation CLI tool to regenerate the types, ensuring the `map` type is correctly mapped to `Record<K, V>` in TypeScript.
Audit
Dependencies
cassandra-driverrequiredRequired runtime peer dependency for connecting to Cassandra and initializing the generated mappers. The package interacts directly with instances of `cassandra-driver.Client`.