@ragestudio/scylla-odm 0.14.0 → 0.15.1

package/README.md

@@ -0,0 +1,246 @@
+# @ragestudio/scylla-odm
+
+> A lightweight ODM for ScyllaDB and Cassandra.
+
+> **Warning:** under active development, not production-ready.
+
+---
+
+## why this exists
+
+Most of (not existent) Node.js ODMs for ScyllaDB/Cassandra rely on the official `cassandra-driver`.
+
+The official `cassandra-driver` ships a built-in mapper, but it has no
+TypeScript support or a friendly interface.
+You define your columns with plain strings and get
+plain objects back — no autocomplete, no type checking, no safety net.
+
+This ODM is built on top of a modified `cassandra-driver` and adds:
+
+- **Type-safe schemas** — your column types are inferred, so `find`,
+  `create`, and `save` all know the shape of your data
+- **ODM Methods** — easier & friendly API for interacting with your data
+- **Full TypeScript support** — autocomplete, type checking, and inference
+  from schema to model to document
+- **MongoDB-style query operators** — `$gt`, `$in`, `$lte`, etc., all typed
+
+We also stripped out everything you probably never use (DataStax Insights,
+metrics, heavy dependencies, and other services) and applied a bunch of performance patches on
+top of the driver itself.
+
+The result is a leaner driver with less overhead, fewer timers, and better
+memory usage.
+
+---
+
+## install
+
+```bash
+npm install @ragestudio/scylla-odm
+```
+
+---
+
+## quick start
+
+```ts
+import Client, { Schema, Model, ColumnTypes } from "@ragestudio/scylla-odm";
+import type { Column } from "@ragestudio/scylla-odm/types";
+
+// 1. define a schema
+const userSchema = new Schema(
+  {
+    table_name: "users",
+    keys: ["id"], // partition key and clustering keys
+  },
+  {
+    id: { type: ColumnTypes.Int, required: true } as Column<number>,
+    name: { type: ColumnTypes.Text, required: true } as Column<string>,
+    email: { type: ColumnTypes.Text, required: true } as Column<string>,
+    age: { type: ColumnTypes.Int } as Column<number>,
+  },
+);
+
+// 2. create a model
+const User = new Model("User", userSchema);
+
+// 3. create a client
+const client = new Client({
+  contactPoints: ["127.0.0.1"],
+  localDataCenter: "datacenter1",
+  keyspace: "myapp",
+});
+
+// 4. initialize and connect
+await client.initialize();
+
+// 4. create and save documents
+const user = User.create({
+  id: 1234,
+  name: "Alice",
+  email: "alice@example.com",
+  age: 30,
+});
+
+await user.save();
+
+// 5. query
+const found = await User.findOne({ id: 1234 });
+console.log(found?.name); // "Alice"
+
+// 6. shutdown
+await client.shutdown();
+```
+
+---
+
+## schema
+
+A schema describes a table: its name, primary keys, and columns.
+
+```ts
+const productSchema = new Schema(
+  {
+    table_name: "products",
+    keys: [["category"], "id"], // compound partition key
+    clustering_order: { created_at: "desc" }, // optional
+  },
+  {
+    category: { type: ColumnTypes.Text, required: true } as Column<string>,
+    id: { type: ColumnTypes.Uuid, required: true } as Column<string>,
+    title: { type: ColumnTypes.Text, required: true } as Column<string>,
+    price: { type: ColumnTypes.Double, required: true } as Column<number>,
+    created_at: { type: ColumnTypes.Timestamp } as Column<Date>,
+  },
+);
+```
+
+---
+
+## model
+
+A model wraps a schema and provides the query interface.
+
+```ts
+const Product = new Model("Product", productSchema);
+```
+
+### methods
+
+| method                     | description                                                                                                                                                                          |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `create(data)` / `obj()`   | create a new document (not persisted yet)                                                                                                                                            |
+| `find(query, options?)`    | find documents matching the query, returns an array of documents                                                                                                                     |
+| `findOne(query, options?)` | find a single document, if no document is found, returns `null`. Due the mapper limitation, note that all partition and clustering keys must be defined in order to use this method. |
+|  |
+| `update(query)`            | update documents matching the query                                                                                                                                                  |
+| `delete(query)`            | delete documents matching the query                                                                                                                                                  |
+| `countAll()`               | count all documents in the table                                                                                                                                                     |
+
+---
+
+## document
+
+Documents are the objects you work with. They carry the data and a few helpers.
+
+```ts
+const product = Product.create({
+  category: "books",
+  id: uuid(),
+  title: "ODM 101",
+  price: 29.99,
+});
+
+await product.save(); // persist to ScyllaDB
+await product.delete(); // delete from ScyllaDB
+product.toRaw(); // plain object without internal fields
+product.getChangedFields(original); // diff between current and original data
+```
+
+---
+
+## query operators
+
+Use MongoDB-style operators in your queries:
+
+```ts
+// exact match
+await User.find({ name: "Alice" });
+
+// comparison operators
+await Product.find({ price: { $gt: 10, $lte: 50 } });
+
+// list matching
+await User.find({ age: { $in: [25, 30, 35] } });
+
+// sorting
+await Product.find({ category: "books" }, { $orderby: { created_at: "desc" } });
+
+// raw results (skip document wrapping)
+const raw = await Product.find({ category: "books" }, { raw: true });
+```
+
+---
+
+## configuration
+
+```ts
+const client = new Client({
+  modelsPath: "./db",
+  contactPoints: ["127.0.0.1"],
+  localDataCenter: "datacenter1",
+  keyspace: "myapp",
+  port: 9042,
+  maxRetries: 3,
+  retryDelay: 1000,
+  pooling: {
+    coreConnectionsPerHost: {
+      local: 2,
+    },
+    maxRequestsPerConnection: 1024,
+  },
+});
+```
+
+You can also configure via environment variables:
+
+| variable                   | default            |
+| -------------------------- | ------------------ |
+| `SCYLLA_CONTACT_POINTS`    | `127.0.0.1`        |
+| `SCYLLA_LOCAL_DATA_CENTER` | `datacenter1`      |
+| `SCYLLA_KEYSPACE`          | `default_keyspace` |
+
+---
+
+## about the driver
+
+This package ships a modified version of the `cassandra-driver`
+
+---
+
+## license
+
+This project is licensed under the [MIT license](https://opensource.org/licenses/MIT).
+
+The bundled `cassandra-driver` is licensed under the
+[Apache License, Version 2.0](src/driver/LICENSE.txt).
+
+```
+Apache Cassandra NodeJS Driver
+Copyright 2013 The Apache Software Foundation
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+```
+
+See [`src/driver/LICENSE.txt`](src/driver/LICENSE.txt) and
+[`src/driver/NOTICE.txt`](src/driver/NOTICE.txt) for the full legal text.

package/_virtual/_rolldown/runtime.js

@@ -0,0 +1 @@
+import{createRequire as e}from"node:module";var t=Object.create,n=Object.defineProperty,r=Object.getOwnPropertyDescriptor,i=Object.getOwnPropertyNames,a=Object.getPrototypeOf,o=Object.prototype.hasOwnProperty,s=(e,t)=>()=>(t||(e((t={exports:{}}).exports,t),e=null),t.exports),c=(e,t,a,s)=>{if(t&&typeof t==`object`||typeof t==`function`)for(var c=i(t),l=0,u=c.length,d;l<u;l++)d=c[l],!o.call(e,d)&&d!==a&&n(e,d,{get:(e=>t[e]).bind(null,d),enumerable:!(s=r(t,d))||s.enumerable});return e},l=(e,r,i)=>(i=e==null?{}:t(a(e)),c(r||!e||!e.__esModule?n(i,`default`,{value:e,enumerable:!0}):i,e)),u=e(import.meta.url);export{s as __commonJSMin,u as __require,l as __toESM};

package/client.d.ts

@@ -1,6 +1,8 @@
+import { mapping } from "./driver/lib/mapping/index.js";
+import { Client as Client$1 } from "./driver/index.js";
 import { Model } from "./model/index.js";
 import { ClientConfig } from "./types.js";
-import { Client as Client$1, mapping } from "cassandra-driver";
+import { Logger } from "./logger/index.js";
 
 //#region src/client.d.ts
 declare class Client {
@@ -10,15 +12,14 @@ declare class Client {
   mapper: mapping.Mapper;
   models: Map<string, Model<any>>;
   model(name: string): Model<any> | undefined;
+  logger: Logger;
   initialize(options?: {
     sync?: boolean;
   }): Promise<void>;
-  private connectWithRetry;
-  private delay;
   shutdown(): Promise<void>;
+  private connectWithRetry;
   executeWithRetry<T>(operation: () => Promise<T>, operationName?: string): Promise<T>;
   private isRetryableError;
 }
 //#endregion
-export { Client, Client as default };
-//# sourceMappingURL=client.d.ts.map
+export { Client, Client as default };

package/client.js

@@ -1,117 +1 @@
-import loadModels_default from "./utils/loadModels.js";
-import buildMapper_default from "./utils/buildMapper.js";
-import { Model } from "./model/index.js";
-import path from "node:path";
-import Cassandra from "cassandra-driver";
-//#region src/client.ts
-const DEFAULT_MAX_RETRIES = 3;
-const DEFAULT_RETRY_DELAY = 1e3;
-const { SCYLLA_CONTACT_POINTS, SCYLLA_LOCAL_DATA_CENTER, SCYLLA_KEYSPACE } = process.env;
-var Client = class {
-	constructor(config = {}) {
-		if (globalThis.__scylla_client) throw new Error("An instance of Scylla Client is already initialized");
-		this.config = {
-			modelsPath: path.resolve(process.cwd(), "db"),
-			contactPoints: config.contactPoints ?? SCYLLA_CONTACT_POINTS?.split(",") ?? ["127.0.0.1"],
-			localDataCenter: config.localDataCenter ?? SCYLLA_LOCAL_DATA_CENTER ?? "datacenter1",
-			keyspace: config.keyspace ?? SCYLLA_KEYSPACE ?? "default",
-			port: 9042,
-			maxRetries: DEFAULT_MAX_RETRIES,
-			retryDelay: DEFAULT_RETRY_DELAY,
-			...config
-		};
-		const clientOptions = {
-			contactPoints: this.config.contactPoints,
-			localDataCenter: this.config.localDataCenter,
-			keyspace: this.config.keyspace,
-			protocolOptions: { port: this.config.port }
-		};
-		if (this.config.pooling) clientOptions.pooling = this.config.pooling;
-		this.driver = new Cassandra.Client(clientOptions);
-	}
-	config;
-	driver;
-	mapper;
-	models = /* @__PURE__ */ new Map();
-	model(name) {
-		return this.models.get(name);
-	}
-	async initialize(options = {}) {
-		let models;
-		try {
-			models = await loadModels_default(this.config.modelsPath);
-		} catch (error) {
-			throw new Error(`Failed to load models: ${error.message}`);
-		}
-		models = models.filter((schema) => schema instanceof Model);
-		this.mapper = new Cassandra.mapping.Mapper(this.driver, { models: buildMapper_default(models) });
-		globalThis.__scylla_client = this;
-		for (let model of models) {
-			this.models.set(model.name, model);
-			if (options?.sync === true) await model._sync();
-		}
-		console.log("Connecting to ScyllaDB");
-		await this.connectWithRetry();
-		console.log("ScyllaDB Connected");
-	}
-	async connectWithRetry() {
-		let lastError = null;
-		for (let attempt = 1; attempt <= this.config.maxRetries; attempt++) try {
-			await this.driver.connect();
-			return;
-		} catch (error) {
-			lastError = error;
-			console.warn(`Connection attempt ${attempt} failed: ${error.message}`);
-			if (attempt < this.config.maxRetries) {
-				console.log(`Retrying in ${this.config.retryDelay}ms...`);
-				await this.delay(this.config.retryDelay);
-			}
-		}
-		throw new Error(`Failed to connect to ScyllaDB after ${this.config.maxRetries} attempts: ${lastError?.message}`);
-	}
-	delay(ms) {
-		return new Promise((resolve) => setTimeout(resolve, ms));
-	}
-	async shutdown() {
-		try {
-			await this.driver.shutdown();
-			console.log("ScyllaDB connection closed");
-			delete globalThis.__scylla_client;
-		} catch (error) {
-			console.error("Error shutting down ScyllaDB connection:", error);
-			throw error;
-		}
-	}
-	async executeWithRetry(operation, operationName = "operation") {
-		let lastError = null;
-		for (let attempt = 1; attempt <= this.config.maxRetries; attempt++) try {
-			return await operation();
-		} catch (error) {
-			lastError = error;
-			if (this.isRetryableError(error) && attempt < this.config.maxRetries) {
-				console.warn(`Operation ${operationName} attempt ${attempt} failed: ${error.message}`);
-				console.log(`Retrying in ${this.config.retryDelay}ms...`);
-				await this.delay(this.config.retryDelay);
-				continue;
-			}
-			throw error;
-		}
-		throw new Error(`Operation ${operationName} failed after ${this.config.maxRetries} attempts: ${lastError?.message}`);
-	}
-	isRetryableError(error) {
-		const retryableMessages = [
-			"timeout",
-			"connection",
-			"network",
-			"unavailable",
-			"overloaded",
-			"no hosts available"
-		];
-		const errorMessage = error.message?.toLowerCase() || "";
-		return retryableMessages.some((msg) => errorMessage.includes(msg));
-	}
-};
-//#endregion
-export { Client, Client as default };
-
-//# sourceMappingURL=client.js.map
+import{__toESM as e}from"./_virtual/_rolldown/runtime.js";import{require_driver as t}from"./driver/index.js";import{Model as n}from"./model/index.js";import{Logger as r}from"./logger/index.js";import i from"./utils/loadModels.js";import a from"./utils/buildMapper.js";import o from"./utils/delay.js";import s from"node:path";var c=e(t(),1);const{SCYLLA_CONTACT_POINTS:l,SCYLLA_LOCAL_DATA_CENTER:u,SCYLLA_KEYSPACE:d}=process.env;var f=class{constructor(e={}){if(globalThis.__scylla_client)throw Error(`An instance of Scylla Client is already initialized`);this.config={modelsPath:s.resolve(process.cwd(),`db`),contactPoints:e.contactPoints??l?.split(`,`)??[`127.0.0.1`],localDataCenter:e.localDataCenter??u??`datacenter1`,keyspace:e.keyspace??d??`default_keyspace`,port:9042,maxRetries:3,retryDelay:1e3,...e};let t={contactPoints:this.config.contactPoints,localDataCenter:this.config.localDataCenter,keyspace:this.config.keyspace,protocolOptions:{port:this.config.port}};this.config.pooling&&(t.pooling=this.config.pooling),this.driver=new c.Client(t)}config;driver;mapper;models=new Map;model(e){return this.models.get(e)}logger=new r;async initialize(e={}){let t;try{t=await i(this.config.modelsPath)}catch(e){throw Error(`Failed to load models: ${e.message}`)}t=t.filter(e=>e instanceof n),this.mapper=new c.mapping.Mapper(this.driver,{models:a(t)}),globalThis.__scylla_client=this,this.logger.log(`Connecting...`),await this.connectWithRetry(),this.logger.log(`Connected`);for(let n of t)this.models.set(n.name,n),e?.sync===!0&&await n._sync()}async shutdown(){try{await this.driver.shutdown(),this.logger.log(`connection closed`),delete globalThis.__scylla_client}catch(e){throw this.logger.error(`error shutting down connection:`,e),e}}async connectWithRetry(){let e=null;for(let t=1;t<=this.config.maxRetries;t++)try{await this.driver.connect();return}catch(n){e=n,this.logger.warn(`Connection attempt ${t} failed: ${n.message}`),t<this.config.maxRetries&&(this.logger.log(`Retrying in ${this.config.retryDelay}ms...`),await o(this.config.retryDelay))}throw Error(`Failed to connect to ScyllaDB after ${this.config.maxRetries} attempts: ${e?.message}`)}async executeWithRetry(e,t=`operation`){let n=null;for(let r=1;r<=this.config.maxRetries;r++)try{return await e()}catch(e){if(n=e,this.isRetryableError(e)&&r<this.config.maxRetries){this.logger.warn(`Operation ${t} attempt ${r} failed: ${e.message}`),this.logger.log(`Retrying in ${this.config.retryDelay}ms...`),await o(this.config.retryDelay);continue}throw e}throw Error(`Operation ${t} failed after ${this.config.maxRetries} attempts: ${n?.message}`)}isRetryableError(e){let t=[`timeout`,`connection`,`network`,`unavailable`,`overloaded`,`no hosts available`],n=e.message?.toLowerCase()||``;return t.some(e=>n.includes(e))}};export{f as Client,f as default};

package/cql_gen/create_keyspace.d.ts

@@ -0,0 +1,11 @@
+//#region src/cql_gen/create_keyspace.d.ts
+type KeyspaceCreateOptions = {
+  keyspace: string;
+  replication?: {
+    strategy: string;
+    options: Record<string, string>;
+  };
+};
+declare function createKeyspace(options: KeyspaceCreateOptions): string;
+//#endregion
+export { createKeyspace as default };

package/cql_gen/create_keyspace.js

@@ -0,0 +1 @@
+function e(e){let t={};return t=e.replication?e.replication:{strategy:`SimpleStrategy`,options:{replication_factor:`1`}},`CREATE KEYSPACE IF NOT EXISTS ${e.keyspace} WITH REPLICATION = ${JSON.stringify(t)};`}export{e as default};

package/cql_gen/create_table.d.ts

@@ -3,5 +3,4 @@ import { Model } from "../model/index.js";
 //#region src/cql_gen/create_table.d.ts
 declare function export_default(model: Model): string;
 //#endregion
-export { export_default as default };
-//# sourceMappingURL=create_table.d.ts.map
+export { export_default as default };

package/cql_gen/create_table.js

@@ -1,38 +1 @@
-//#region src/cql_gen/create_table.ts
-function create_table_default(model) {
-	const desc = model.schema;
-	const tableName = desc.table_name;
-	const keyspace = model.client.config.keyspace;
-	const fields = desc.fields;
-	const key = desc.keys;
-	const clusteringOrder = desc.clustering_order;
-	let columnsDef = "";
-	for (const fieldName in fields) {
-		const field = fields[fieldName];
-		const typeStr = typeof field === "string" ? field : field?.type;
-		if (!typeStr) throw new Error(`Invalid field type for "${fieldName}" in model "${tableName}"`);
-		columnsDef += `"${fieldName}" ${typeStr.toUpperCase()}, `;
-	}
-	let pkDef = "";
-	if (typeof key === "string") pkDef = `"${key}"`;
-	else if (Array.isArray(key) && key.length > 0) {
-		const first = key[0];
-		if (Array.isArray(first)) pkDef = `(${first.map((k) => `"${k}"`).join(", ")})`;
-		else pkDef = `"${first}"`;
-		for (let i = 1; i < key.length; i++) pkDef += `, "${key[i]}"`;
-	} else throw new Error(`Missing or invalid primary key in model "${tableName}"`);
-	let clusterClause = "";
-	if (clusteringOrder) {
-		let orderDef = "";
-		for (const col in clusteringOrder) {
-			if (orderDef !== "") orderDef += ", ";
-			orderDef += `"${col}" ${clusteringOrder[col].toUpperCase()}`;
-		}
-		if (orderDef !== "") clusterClause = ` WITH CLUSTERING ORDER BY (${orderDef})`;
-	}
-	return `CREATE TABLE IF NOT EXISTS ${keyspace}.${tableName} (${columnsDef}PRIMARY KEY (${pkDef}))${clusterClause}`;
-}
-//#endregion
-export { create_table_default as default };
-
-//# sourceMappingURL=create_table.js.map
+function e(e){let t=e.schema,n=t.table_name,r=e.client.config.keyspace,i=t.fields,a=t.keys,o=t.clustering_order,s=``;for(let e in i){let t=i[e],r=typeof t==`string`?t:t?.type;if(!r)throw Error(`Invalid field type for "${e}" in model "${n}"`);s+=`"${e}" ${r.toUpperCase()}, `}let c=``;if(typeof a==`string`)c=`"${a}"`;else if(Array.isArray(a)&&a.length>0){let e=a[0];c=Array.isArray(e)?`(${e.map(e=>`"${e}"`).join(`, `)})`:`"${e}"`;for(let e=1;e<a.length;e++)c+=`, "${a[e]}"`}else throw Error(`Missing or invalid primary key in model "${n}"`);let l=``;if(o){let e=``;for(let t in o)e!==``&&(e+=`, `),e+=`"${t}" ${o[t].toUpperCase()}`;e!==``&&(l=` WITH CLUSTERING ORDER BY (${e})`)}return`CREATE TABLE IF NOT EXISTS ${r}.${n} (${s}PRIMARY KEY (${c}))${l}`}export{e as default};

package/document/index.d.ts

@@ -1,17 +1,16 @@
+import { mapping } from "../driver/lib/mapping/index.js";
 import { Model } from "../model/index.js";
 import { Doc } from "../types.js";
-import * as _$cassandra_driver0 from "cassandra-driver";
 
 //#region src/document/index.d.ts
 declare class Document<TDoc = any> {
   constructor(data: TDoc, model: Model<any, TDoc>);
   _model: Model<any, TDoc>;
   save(): Promise<Doc<TDoc>>;
-  delete(): Promise<_$cassandra_driver0.mapping.Result<any>>;
+  delete(): Promise<mapping.Result<any>>;
   toRaw(): TDoc;
   isValid(): boolean;
   getChangedFields(original: Partial<TDoc>): (keyof TDoc)[];
 }
 //#endregion
-export { Document, Document as default };
-//# sourceMappingURL=index.d.ts.map
+export { Document, Document as default };

package/document/index.js

@@ -1,63 +1 @@
-//#region src/document/index.ts
-var Document = class {
-	constructor(data, model) {
-		if (data == null) throw new Error("Cannot create Document with null or undefined data");
-		if (typeof data !== "object" || Array.isArray(data)) throw new Error("Document data must be an object");
-		Object.assign(this, data);
-		Object.defineProperty(this, "_model", {
-			value: model,
-			enumerable: false,
-			writable: false,
-			configurable: false
-		});
-	}
-	_model;
-	async save() {
-		try {
-			const data = this.toRaw();
-			return await this._model.update(data);
-		} catch (error) {
-			throw new Error(`Failed to save document: ${error.message}`);
-		}
-	}
-	async delete() {
-		try {
-			return await this._model.delete(this.toRaw());
-		} catch (error) {
-			throw new Error(`Failed to delete document: ${error.message}`);
-		}
-	}
-	toRaw() {
-		const raw = {};
-		for (const key in this) {
-			if (key === "_model") continue;
-			if (this.propertyIsEnumerable(key)) {
-				const value = this[key];
-				try {
-					JSON.stringify(value);
-					raw[key] = value;
-				} catch (error) {
-					raw[key] = String(value);
-				}
-			}
-		}
-		return raw;
-	}
-	isValid() {
-		try {
-			return true;
-		} catch {
-			return false;
-		}
-	}
-	getChangedFields(original) {
-		const current = this.toRaw();
-		const changed = [];
-		for (const key in current) if (!(key in original) || current[key] !== original[key]) changed.push(key);
-		return changed;
-	}
-};
-//#endregion
-export { Document, Document as default };
-
-//# sourceMappingURL=index.js.map
+var e=class{constructor(e,t){if(e==null)throw Error(`Cannot create Document with null or undefined data`);if(typeof e!=`object`||Array.isArray(e))throw Error(`Document data must be an object`);Object.assign(this,e),Object.defineProperty(this,`_model`,{value:t,enumerable:!1,writable:!1,configurable:!1})}_model;async save(){try{let e=this.toRaw();return await this._model.update(e)}catch(e){throw Error(`Failed to save document: ${e.message}`)}}async delete(){try{return await this._model.delete(this.toRaw())}catch(e){throw Error(`Failed to delete document: ${e.message}`)}}toRaw(){let e={};for(let t in this)if(t!==`_model`&&this.propertyIsEnumerable(t)){let n=this[t];try{JSON.stringify(n),e[t]=n}catch{e[t]=String(n)}}return e}isValid(){try{return!0}catch{return!1}}getChangedFields(e){let t=this.toRaw(),n=[];for(let r in t)(!(r in e)||t[r]!==e[r])&&n.push(r);return n}};export{e as Document,e as default};