CassandraORM JS

Um ORM moderno e otimizado para Apache Cassandra e ScyllaDB com suporte nativo ao TypeScript, recursos ES6+ e capacidades avançadas.

🚀 Recursos

Recursos Principais

• TypeScript First - Suporte nativo com tipos completos
• Módulos ES6+ - Sintaxe moderna de import/export
• Async/Await - API baseada em Promises
• Auto-Criação - Criação automática de keyspaces e tabelas
• Validação de Schema - Validação abrangente de dados
• Constraints Únicos - Previne inserção de dados duplicados

Recursos Avançados

• Query Builder - API fluente para queries complexas
• Cache Inteligente - Estratégias de cache LRU/LFU/FIFO
• Operações em Lote - Bulk writer estilo MongoDB com processamento em lotes
• Paginação Otimizada - Paginação baseada em token e cursor
• Hooks & Middleware - Ciclo de vida extensível de operações
• Monitoramento de Performance - Métricas e observabilidade integradas

📦 Instalação

npm install cassandraorm-js

⚡ Início Rápido

Uso Básico

const { CassandraORM } = require('cassandraorm-js');

const orm = new CassandraORM({
  contactPoints: ['127.0.0.1'],
  localDataCenter: 'datacenter1',
  keyspace: 'meuapp'
});

await orm.connect();

// Definir modelo
const User = orm.model('users', {
  id: 'uuid',
  name: 'text',
  email: 'text',
  createdAt: 'timestamp'
}, {
  key: ['id']
});

await User.createTable();

// Criar usuário
const user = await User.create({
  id: orm.uuid(),
  name: 'João Silva',
  email: '[email protected]',
  createdAt: new Date()
});

Uso Moderno com TypeScript

import { createClient } from 'cassandraorm-js';

const client = createClient({
  clientOptions: {
    contactPoints: ['127.0.0.1'],
    localDataCenter: 'datacenter1',
    keyspace: 'meuapp'
  },
  ormOptions: {
    createKeyspace: true, // Auto-criar keyspace
    migration: 'safe'     // Auto-criar tabelas
  }
});

await client.connect(); // Cria keyspace automaticamente

const User = await client.loadSchema('users', {
  fields: {
    id: 'uuid',
    email: { 
      type: 'text', 
      unique: true,
      validate: {
        required: true,
        isEmail: true
      }
    },
    name: {
      type: 'text',
      validate: {
        required: true,
        minLength: 2
      }
    },
    age: {
      type: 'int',
      validate: {
        min: 0,
        max: 120
      }
    }
  },
  key: ['id']
}); // Cria tabela automaticamente com validação

Query Builder Avançado

import { AdvancedQueryBuilder } from 'cassandraorm-js';

const queryBuilder = new AdvancedQueryBuilder(client.driver, 'users', 'meuapp');

const users = await queryBuilder
  .select(['name', 'email', 'age'])
  .where('status').eq('ativo')
  .and('age').gte(18)
  .and('categoria').in(['premium', 'gold'])
  .orderBy('created_at', 'DESC')
  .limit(50)
  .allowFiltering()
  .execute();

Operações em Lote

import { BulkWriter } from 'cassandraorm-js';

const bulkWriter = new BulkWriter(client.driver, 'meuapp', {
  batchSize: 100,
  skipDuplicates: true
});

bulkWriter
  .insert('users', { id: client.uuid(), name: 'Usuário 1', email: '[email protected]' })
  .insert('users', { id: client.uuid(), name: 'Usuário 2', email: '[email protected]' })
  .update('users', { age: 26 }, { email: '[email protected]' });

const result = await bulkWriter.execute();
console.log(`Inseridos: ${result.inserted}, Atualizados: ${result.updated}`);

Cache Inteligente

import { IntelligentCache, QueryCache } from 'cassandraorm-js';

const cache = new IntelligentCache({
  ttl: 300,        // 5 minutos
  maxSize: 1000,   // Máximo 1000 itens
  strategy: 'lru'  // Least Recently Used
});

const queryCache = new QueryCache({ ttl: 600 });

// Cache de queries automático
const query = 'SELECT * FROM users WHERE status = ?';
const params = ['ativo'];

let result = queryCache.get(query, params);
if (!result) {
  result = await client.execute(query, params);
  queryCache.set(query, params, result.rows);
}

Hooks e Middleware

import { HooksMiddlewareSystem, CommonHooks } from 'cassandraorm-js';

const hooks = new HooksMiddlewareSystem();

// Adicionar timestamps automaticamente
hooks.beforeCreate(CommonHooks.addTimestamps);
hooks.beforeUpdate(CommonHooks.updateTimestamp);

// Adicionar validação
hooks.beforeCreate(CommonHooks.validate(userSchema));

// Adicionar hook personalizado
hooks.beforeCreate(async (data) => {
  if (data.password) {
    data.password = await hashPassword(data.password);
  }
  return data;
});

// Executar com hooks
const result = await hooks.executeOperation(
  'create',
  userData,
  { operation: 'create', tableName: 'users' },
  async () => {
    return await client.execute(
      'INSERT INTO users (id, name, email) VALUES (?, ?, ?)',
      [userData.id, userData.name, userData.email]
    );
  }
);

📚 Documentação

Português

• Guia de Instalação
• Guia de Migração
• Referência da API
• Recursos Avançados
• Auto-Criação
• Operações em Lote
• Exemplos

English

• Installation Guide
• Migration Guide
• API Reference
• Examples

🌍 Idiomas

• English
• Português (atual)

🔄 Migração

CassandraORM JS é compatível com Express-Cassandra, facilitando a migração.

🧪 Testes

# Executar todos os testes
npm test

# Executar testes específicos
npm run test:ci        # Testes CI
npm run test:bun       # Testes Bun
npm run test:bulk      # Operações em lote
npm run test:features  # Recursos avançados

🤝 Contribuindo

Contribuições são bem-vindas! Veja CONTRIBUTING.md para detalhes.

📄 Licença

Licença MIT - veja o arquivo LICENSE para detalhes.

🔗 Links

• Pacote NPM
• Repositório GitHub
• Documentação
• Exemplos

⭐ Suporte

Se este projeto foi útil para você, por favor dê uma estrela no GitHub!