typecql

library1.1.17jsnpmunverified

TypeCQL is an ORM for CQL databases like Cassandra and ScyllaDB, currently at version 1.1.17. It provides a built-in mapper with custom columns and options, an excellent type system (TypeScript 5+), query optimization, support for multiple connections, advanced methods, automatic loading of tables and columns, a migration tool, and transactions. It works with both NestJS and plain TypeScript Node.js. Key differentiators include its advanced type inference and seamless integration with NestJS, making it a strong alternative to other CQL ORMs like cassandra-driver's mapper or express-cassandra.

database

npm install typecql

package ↗

INSTALL

IMPORT

SIG · TYPECQL

typecql

databasejavascriptv1.1.17

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Connection

✓ import { Connection } from 'typecql'

Default export is not available; use named import for Connection.

Entity

✓ import { Entity } from 'typecql'

✗ const Entity = require('typecql').Entity

ESM import is preferred; CommonJS require also works but may lack TypeScript types.

Table

✓ import { Table } from 'typecql'

✗ import { table } from 'typecql'

Case-sensitive: 'Table' with capital T, not 'table'.

Defines a User entity and demonstrates connecting to a Cassandra cluster, saving a new user, and retrieving it by primary key.

import { Connection, Entity, Table } from 'typecql'; @Entity({ keyspace: 'my_keyspace', table: 'users' }) class User { @Table.PartitionKey() id: string; @Table.Column() name: string; @Table.Column() email: string; } async function main() { const conn = new Connection({ contactPoints: ['127.0.0.1:9042'], localDataCenter: 'datacenter1', credentials: { username: 'cassandra', password: 'cassandra' }, }); await conn.connect(); const user = new User(); user.id = '1'; user.name = 'Alice'; user.email = 'alice@example.com'; await conn.save(user); const retrieved = await conn.findOne(User, { id: '1' }); console.log(retrieved); await conn.close(); } main().catch(console.error);

Debug

Known issues

gotchaTypeCQL requires a running Cassandra or ScyllaDB instance; connection errors are common if the database is not reachable.

fix

Ensure your Cassandra or ScyllaDB cluster is running and accessible from the configured contact points.

affects: all

breakingIn version 1.0.0, the Connection constructor changed from accepting an object with 'hosts' to 'contactPoints'. Old code using 'hosts' will break.

fix

Update Connection configuration: replace { hosts: [...] } with { contactPoints: [...] }.

affects: <1.0.0

deprecatedThe method 'findOne' is deprecated in favor of 'findFirst' since version 1.1.0.

fix

Replace 'findOne' with 'findFirst' in your code.

affects: >=1.1.0

gotchaTypeCQL uses TypeScript decorators which require 'experimentalDecorators' and 'emitDecoratorMetadata' to be enabled in tsconfig.json.

fix

Add the following to tsconfig.json: "experimentalDecorators": true, "emitDecoratorMetadata": true.

affects: all

breakingStarting from version 1.2.0 (future), the 'save' method will no longer return the entity but a SaveResult object. You must adapt code that expects the entity back.

fix

Check the return type of save() and use SaveResult.entity to get the saved entity.

affects: >=1.2.0

Errors

Common errors & fixes

Cannot find module 'typecql' or its corresponding type declarations.

Missing installation or incorrect import path.

fix

Install typecql: npm install typecql. Ensure you are using the correct import: import { ... } from 'typecql'.

TypeError: Class constructor Connection cannot be invoked without 'new'

Using CommonJS require without calling new.

fix

Use import: import { Connection } from 'typecql' and then instantiate with new Connection(...).

experimentalDecorators not enabled

Decorators require TypeScript compiler options.

fix

Set "experimentalDecorators": true in tsconfig.json.

Upgrade

Version history

1.1.17latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node