Registry / database / imean-cassandra-orm

imean-cassandra-orm

library4.0.0jsnpmunverified

IMean Cassandra ORM (v2) is a TypeScript-first ORM for Apache Cassandra and ScyllaDB, built on Zod for type-safe schema definitions. The current stable version is 4.0.0, requiring Node.js >=20 and Zod v4.x. It provides automatic CQL generation, schema synchronization (auto-migration), optional ClickHouse dual-write for analytics, and ANN vector search. Unlike Cassandra drivers alone, it offers a high-level abstraction with runtime validation and type inference from Zod schemas. The library ships TypeScript types and is released under the MIT license.

database

npm install imean-cassandra-orm

package ↗

INSTALL

IMPORT

SIG · IMEAN-CASSANDRA-OR

imean-cassandra-orm

databasejavascriptv4.0.0

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.

defineTable

✓ import { defineTable } from 'imean-cassandra-orm'

✗ const { defineTable } = require('imean-cassandra-orm')

ESM-only since v3; CommonJS require not supported.

createClientV2

✓ import { createClientV2 } from 'imean-cassandra-orm'

✗ import createClientV2 from 'imean-cassandra-orm'

Named export, not default. Use through ESM only.

Types

✓ import { Types } from 'imean-cassandra-orm'

✗ import { Types } from 'cassandra-driver'

Types utility is re-exported from the ORM package, not from cassandra-driver.

Defines a Cassandra table schema with Zod, initializes a client, synchronizes the schema, performs a basic insert and query, then shuts down.

import { z } from 'zod'; import { defineTable, createClientV2, Types } from 'imean-cassandra-orm'; const userSchema = defineTable({ keyspace: 'my_keyspace', tableName: 'users', fields: { user_id: z.string(), email: z.string().email(), name: z.string(), age: z.number().int().positive(), is_active: z.boolean(), metadata: Types.json(), created_at: z.date(), }, partitionKey: ['user_id'], }); const { client, shutdown } = await createClientV2({ cassandra: { contactPoints: ['127.0.0.1'], localDataCenter: 'datacenter1' }, }); const userModel = client.model(userSchema); await userModel.syncSchema(); await userModel.insert({ user_id: 'u1', email: 'u1@example.com', name: 'Alice', age: 20, is_active: true, metadata: { score: 95 }, created_at: new Date() }); const found = await userModel.findOne({ user_id: 'u1' }); await shutdown();

Debug

Known issues

breakingZod v4 is required. Upgrade from v3 may break schema definitions due to Zod API changes.

fix

Update Zod to v4 and adjust any Zod schema definitions to be compatible with Zod v4 (e.g., refine syntax).

affects: >=4.0.0

breakingESM-only package. CommonJS require() will throw Module not found errors.

fix

Use import syntax or set type: module in package.json. If you must use CommonJS, pin to version 2.x.

affects: >=3.0.0

breakingcreateClientV2 replaces older createClient function. Old createClient still exists but may be deprecated.

fix

Use createClientV2 for new projects. For existing code, check if createClient is still exported.

affects: >=4.0.0

deprecatedcreateClient function (v1) may be deprecated in future versions; use createClientV2.

fix

Replace createClient with createClientV2. The new function returns { client, shutdown }.

affects: >=4.0.0

gotchaOptional dependencies like ClickHouse config are not validated eagerly; missing or invalid config may fail at runtime.

fix

Always provide valid ClickHouse config if ClickHouse feature is needed; otherwise omit it.

affects: >=4.0.0

gotchasyncSchema() may drop or alter columns if schema changes; inconsistent schema can lead to data loss.

fix

Manually backup data before running syncSchema() on production tables.

affects: >=4.0.0

Errors

Common errors & fixes

Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'imean-cassandra-orm'

ESM-only package; using CommonJS require without type: module.

fix

Use import syntax or set type: module in package.json.

TypeError: (0 , imean_cassandra_orm.createClientV2) is not a function

Using default import instead of named import.

fix

Use `import { createClientV2 } from 'imean-cassandra-orm'`.

ZodError: Validation failed for schema 'users'

Zod schema definition is incompatible with Zod v4 or missing required fields.

fix

Update Zod to v4 and ensure all Zod schemas use v4 syntax (e.g., z.string().email() is fine, but check any custom refinements).

ReferenceError: module is not defined

Package is ESM-only and does not support module.exports.

fix

Use import/export syntax only.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

@opentelemetry/apioptionalOpenTelemetry API for distributed tracing, required as peer dependency if instrumentation is enabled

cassandra-driverrequiredOfficial DataStax Cassandra driver for Node.js, handles CQL connections and queries

zodrequiredZod v4.x for schema definition and runtime validation, replaces internal validation

Agent activity

4 hits · last 30 days

node

Resources

packageimean-cassandra-orm ↗