{"id":41288,"library":"imean-cassandra-orm","title":"IMean Cassandra ORM","description":"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.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","cassandra","orm","database","node","typescript"],"install":[{"cmd":"npm install imean-cassandra-orm","lang":"bash","label":"npm"},{"cmd":"yarn add imean-cassandra-orm","lang":"bash","label":"yarn"},{"cmd":"pnpm add imean-cassandra-orm","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"OpenTelemetry API for distributed tracing, required as peer dependency if instrumentation is enabled","package":"@opentelemetry/api","optional":true},{"reason":"Official DataStax Cassandra driver for Node.js, handles CQL connections and queries","package":"cassandra-driver","optional":false},{"reason":"Zod v4.x for schema definition and runtime validation, replaces internal validation","package":"zod","optional":false}],"imports":[{"note":"ESM-only since v3; CommonJS require not supported.","wrong":"const { defineTable } = require('imean-cassandra-orm')","symbol":"defineTable","correct":"import { defineTable } from 'imean-cassandra-orm'"},{"note":"Named export, not default. Use through ESM only.","wrong":"import createClientV2 from 'imean-cassandra-orm'","symbol":"createClientV2","correct":"import { createClientV2 } from 'imean-cassandra-orm'"},{"note":"Types utility is re-exported from the ORM package, not from cassandra-driver.","wrong":"import { Types } from 'cassandra-driver'","symbol":"Types","correct":"import { Types } from 'imean-cassandra-orm'"}],"quickstart":{"code":"import { z } from 'zod';\nimport { defineTable, createClientV2, Types } from 'imean-cassandra-orm';\n\nconst userSchema = defineTable({\n  keyspace: 'my_keyspace',\n  tableName: 'users',\n  fields: {\n    user_id: z.string(),\n    email: z.string().email(),\n    name: z.string(),\n    age: z.number().int().positive(),\n    is_active: z.boolean(),\n    metadata: Types.json(),\n    created_at: z.date(),\n  },\n  partitionKey: ['user_id'],\n});\n\nconst { client, shutdown } = await createClientV2({\n  cassandra: { contactPoints: ['127.0.0.1'], localDataCenter: 'datacenter1' },\n});\n\nconst userModel = client.model(userSchema);\nawait userModel.syncSchema();\nawait userModel.insert({ user_id: 'u1', email: 'u1@example.com', name: 'Alice', age: 20, is_active: true, metadata: { score: 95 }, created_at: new Date() });\nconst found = await userModel.findOne({ user_id: 'u1' });\nawait shutdown();","lang":"typescript","description":"Defines a Cassandra table schema with Zod, initializes a client, synchronizes the schema, performs a basic insert and query, then shuts down."},"warnings":[{"fix":"Update Zod to v4 and adjust any Zod schema definitions to be compatible with Zod v4 (e.g., refine syntax).","message":"Zod v4 is required. Upgrade from v3 may break schema definitions due to Zod API changes.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Use import syntax or set type: module in package.json. If you must use CommonJS, pin to version 2.x.","message":"ESM-only package. CommonJS require() will throw Module not found errors.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use createClientV2 for new projects. For existing code, check if createClient is still exported.","message":"createClientV2 replaces older createClient function. Old createClient still exists but may be deprecated.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Replace createClient with createClientV2. The new function returns { client, shutdown }.","message":"createClient function (v1) may be deprecated in future versions; use createClientV2.","severity":"deprecated","affected_versions":">=4.0.0"},{"fix":"Always provide valid ClickHouse config if ClickHouse feature is needed; otherwise omit it.","message":"Optional dependencies like ClickHouse config are not validated eagerly; missing or invalid config may fail at runtime.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Manually backup data before running syncSchema() on production tables.","message":"syncSchema() may drop or alter columns if schema changes; inconsistent schema can lead to data loss.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"search_vec":"'20':36 '4.0.0':33 'abstract':71 'alon':64 'analyt':56 'ann':58 'apach':15 'auto':48 'auto-migr':47 'automat':42 'built':19 'cassandra':2,5,16,62,94 'clickhous':51 'cql':43 'current':29 'databas':96 'definit':27 'driver':63 'dual':53 'dual-writ':52 'first':12 'generat':44 'high':69 'high-level':68 'imean':1,4 'infer':77 'javascript':93 'level':70 'librari':82 'licens':92 'migrat':49 'mit':91 'node':97 'node.js':35 'offer':66 'option':50 'orm':3,6,13,95 'provid':41 'releas':88 'requir':34 'runtim':73 'safe':25 'schema':26,45,80 'scylladb':18 'search':60 'ship':83 'stabl':30 'synchron':46 'type':24,76,85 'type-saf':23 'typescript':11,84,98 'typescript-first':10 'unlik':61 'v2':7 'v4.x':39 'valid':74 'vector':59 'version':31 'write':54 'zod':21,38,79","created_at":"2026-06-04T18:51:41.165077+00:00","updated_at":"2026-06-04T18:51:41.165077+00:00","problems":[{"fix":"Use import syntax or set type: module in package.json.","cause":"ESM-only package; using CommonJS require without type: module.","error":"Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'imean-cassandra-orm'"},{"fix":"Use `import { createClientV2 } from 'imean-cassandra-orm'`.","cause":"Using default import instead of named import.","error":"TypeError: (0 , imean_cassandra_orm.createClientV2) is not a function"},{"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).","cause":"Zod schema definition is incompatible with Zod v4 or missing required fields.","error":"ZodError: Validation failed for schema 'users'"},{"fix":"Use import/export syntax only.","cause":"Package is ESM-only and does not support module.exports.","error":"ReferenceError: module is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":null,"npm":"imean-cassandra-orm","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-04","next_check":"2026-09-02","install_tag":null}}