JSPM

hashub-vector

1.0.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 2
  • Score
    100M100P100Q29293F
  • License MIT

Official TypeScript/JavaScript SDK for Hashub Vector API - High-quality multilingual text embeddings with Turkish excellence

Package Exports

  • hashub-vector
  • hashub-vector/dist/index.esm.js
  • hashub-vector/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (hashub-vector) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Hashub Vector SDK for TypeScript/JavaScript

npm version TypeScript Node.js 16+ License: MIT Downloads

High-quality multilingual text embeddings with Turkish excellence 🇹🇷

The official TypeScript/JavaScript SDK for Hashub Vector API - providing state-of-the-art text embeddings with exceptional Turkish language support and 80+ other languages.

🚀 Features

  • 6 Premium Models - From ultra-fast to premium quality
  • Turkish Excellence - Optimized for Turkish market with exceptional Turkish language performance
  • 80+ Languages - Comprehensive multilingual support
  • Full TypeScript Support - Complete type definitions and IntelliSense
  • Modern JavaScript - ES modules, async/await, and Promise-based API
  • Browser & Node.js - Works in both environments
  • OpenAI Compatible - Drop-in replacement for OpenAI embeddings
  • Smart Retry Logic - Automatic retries with exponential backoff
  • Zero Dependencies - Only axios as runtime dependency

📦 Installation

npm install hashub-vector

For TypeScript projects (types included):

npm install hashub-vector

For browser usage via CDN:

<script src="https://unpkg.com/hashub-vector@latest/dist/index.esm.js" type="module"></script>

🏃‍♂️ Quick Start

TypeScript Example

import { HashubVector } from 'hashub-vector';

// Initialize client
const client = new HashubVector({
  apiKey: 'your-api-key'
});

// Single text embedding
const response = await client.vectorize({
  text: 'Merhaba dünya! Hashub ile güçlü vektör embedding\'ler.',
  model: 'gte_base'
});

console.log(`Vector dimension: ${response.dimension}`);
console.log(`First 5 dimensions: ${response.vector.slice(0, 5)}`);

// Batch processing
const batchResponse = await client.vectorizeBatch({
  texts: [
    'Artificial intelligence is transforming the world',
    'Yapay zeka dünyayı dönüştürüyor',
    'L\'intelligence artificielle transforme le monde'
  ],
  model: 'gte_base'
});

console.log(`Processed ${batchResponse.count} texts`);
console.log(`Total tokens: ${batchResponse.totalTokens}`);

JavaScript (ES Modules) Example

import { HashubVector } from 'hashub-vector';

const client = new HashubVector({
  apiKey: process.env.HASHUB_API_KEY
});

// Calculate similarity
const similarity = await client.similarity({
  text1: 'Machine learning',
  text2: 'Makine öğrenmesi',
  model: 'gte_base'
});

console.log(`Similarity: ${similarity.similarity.toFixed(3)}`);

CommonJS Example

const { HashubVector } = require('hashub-vector');

const client = new HashubVector({
  apiKey: 'your-api-key'
});

async function example() {
  const response = await client.vectorize({
    text: 'Example text',
    model: 'e5_base'
  });
  
  console.log(response.vector);
}

🎯 Model Selection Guide

Model Best For Dimension Max Tokens Price/1M Turkish Support
gte_base Long documents, RAG 768 8,192 $0.01 ⭐⭐⭐⭐⭐
nomic_base General purpose 768 2,048 $0.005 ⭐⭐⭐⭐
e5_base Search, retrieval 768 512 $0.003 ⭐⭐⭐⭐⭐
mpnet_base Q&A, similarity 768 512 $0.0035 ⭐⭐⭐⭐⭐
e5_small High volume, speed 384 512 $0.002 ⭐⭐⭐⭐
minilm_base Ultra-fast 384 512 $0.0025 ⭐⭐⭐⭐

Turkish Market Optimization

All models provide excellent Turkish language support, with gte_base, e5_base, and mpnet_base offering the highest quality for Turkish text processing.

// Optimized for Turkish content
const response = await client.vectorize({
  text: 'Hashub Vector API ile Türkçe metinlerinizi güçlü vektörlere dönüştürün!',
  model: 'gte_base'  // Best for Turkish
});

🔄 OpenAI Compatibility

Drop-in replacement for OpenAI's embedding API:

// OpenAI style (compatible)
const response = await client.createEmbedding({
  input: 'Your text here',
  model: 'e5_base'
});

const embedding = response.data[0].embedding;
console.log(`Generated ${embedding.length}D embedding`);

// Multiple texts
const response = await client.createEmbedding({
  input: ['Text 1', 'Text 2', 'Text 3'],
  model: 'gte_base'
});

🧠 Advanced Features

Configuration Options

const client = new HashubVector({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.vector.hashub.dev',  // Custom endpoint
  timeout: 30000,                             // 30 second timeout
  maxRetries: 3,                             // Retry failed requests
  headers: {                                 // Custom headers
    'X-Custom-Header': 'value'
  }
});

Chunking for Long Documents

// Automatic chunking for long texts
const response = await client.vectorize({
  text: longDocument,
  model: 'gte_base',
  chunkSize: 1024,
  chunkOverlap: 0.1  // 10% overlap
});

console.log(`Document split into ${response.chunkCount} chunks`);

Model Information

// Get available models
const models = await client.getModels();

for (const model of models) {
  console.log(`${model.alias}: ${model.description}`);
  console.log(`  Dimension: ${model.dimension}`);
  console.log(`  Max tokens: ${model.maxTokens}`);
  console.log(`  Turkish support: ${model.turkishSupport}/5`);
}

Usage Monitoring

// Check your usage
const usage = await client.getUsage();
console.log(`Tokens used: ${usage.tokensUsed.toLocaleString()}`);
console.log(`Usage percentage: ${usage.tokensPercentageUsed.toFixed(1)}%`);

// Detailed usage with date range
const detailedUsage = await client.getDetailedUsage('2025-08-01', '2025-08-07');
console.log(`Daily breakdown: ${detailedUsage.dailyUsage.length} days`);

🛠️ Integration Examples

With React/Next.js

import { HashubVector } from 'hashub-vector';
import { useState, useEffect } from 'react';

function EmbeddingComponent() {
  const [client] = useState(() => new HashubVector({
    apiKey: process.env.NEXT_PUBLIC_HASHUB_API_KEY!
  }));
  
  const [embedding, setEmbedding] = useState<number[]>([]);

  const generateEmbedding = async (text: string) => {
    try {
      const response = await client.vectorize({
        text,
        model: 'e5_base'
      });
      setEmbedding(response.vector);
    } catch (error) {
      console.error('Embedding failed:', error);
    }
  };

  return (
    <div>
      <button onClick={() => generateEmbedding('Example text')}>
        Generate Embedding
      </button>
      {embedding.length > 0 && (
        <p>Generated {embedding.length}D embedding</p>
      )}
    </div>
  );
}

With Express.js

import express from 'express';
import { HashubVector } from 'hashub-vector';

const app = express();
const client = new HashubVector({
  apiKey: process.env.HASHUB_API_KEY!
});

app.use(express.json());

app.post('/embed', async (req, res) => {
  try {
    const { text, model = 'e5_base' } = req.body;
    
    const response = await client.vectorize({ text, model });
    
    res.json({
      success: true,
      embedding: response.vector,
      dimension: response.dimension,
      tokens: response.tokens
    });
  } catch (error) {
    res.status(500).json({
      success: false,
      error: error.message
    });
  }
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

🔧 Error Handling

import {
  HashubVector,
  AuthenticationError,
  RateLimitError,
  QuotaExceededError,
  ValidationError,
  ServerError,
  NetworkError,
  TimeoutError
} from 'hashub-vector';

const client = new HashubVector({ apiKey: 'your-key' });

try {
  const response = await client.vectorize({
    text: 'Your text',
    model: 'e5_base'
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof QuotaExceededError) {
    console.log('Quota exceeded. Please upgrade your plan');
  } else if (error instanceof NetworkError) {
    console.log('Network connection issue');
  } else if (error instanceof TimeoutError) {
    console.log('Request timeout');
  }
}

🌍 Language Support

Hashub Vector SDK supports 80+ languages with excellent Turkish performance:

Tier 1 (Excellent Performance)

🇹🇷 Turkish, English, German, French, Spanish, Italian, Portuguese, Dutch, Russian, Polish, Czech, Swedish, Danish, Norwegian, Finnish, Ukrainian

Tier 2 (Very Good Performance)

Arabic, Persian, Chinese, Japanese, Korean, Hindi, Bengali, Indonesian, Malay, Thai, Vietnamese, Bulgarian, Romanian, Hungarian, Croatian

Tier 3 (Good Performance)

And 50+ additional languages including African, South Asian, and other European languages.

📊 Performance Benchmarks

Speed Comparison (texts/second)

  • minilm_base: ~950 texts/second (Ultra-fast)
  • e5_small: ~780 texts/second (Fast)
  • e5_base: ~520 texts/second (Balanced)
  • mpnet_base: ~465 texts/second (Quality)
  • nomic_base: ~350 texts/second (Premium)
  • gte_base: ~280 texts/second (Maximum quality)

Bundle Size

  • Minified: ~45KB
  • Gzipped: ~12KB
  • Dependencies: axios only
  • Tree-shakable: Yes

🧪 Testing

Run the test suite:

npm test

Run with coverage:

npm run test:coverage

Run examples:

npm run example:basic
npm run example:async

📚 API Reference

HashubVector Class

Constructor

  • new HashubVector(config: HashubVectorConfig)

Methods

  • vectorize(request: VectorizeRequest): Promise<VectorizeResponse>
  • vectorizeBatch(request: VectorizeBatchRequest): Promise<VectorizeBatchResponse>
  • similarity(request: SimilarityRequest): Promise<SimilarityResponse>
  • getModels(): Promise<ModelInfo[]>
  • getUsage(): Promise<UsageStats>
  • getDetailedUsage(from?, to?): Promise<UsageResponse>
  • createEmbedding(request: OpenAIEmbeddingRequest): Promise<OpenAIEmbeddingResponse>

Type Definitions

Full TypeScript definitions are included. Import types:

import type {
  HashubVectorConfig,
  EmbeddingModel,
  VectorizeRequest,
  VectorizeResponse,
  // ... other types
} from 'hashub-vector';

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

# Development setup
git clone https://github.com/hasanbahadir/hashub-vector-js-sdk.git
cd hashub-vector-js-sdk
npm install
npm run build

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

🚀 What's Next?

Check out our roadmap for upcoming features:

  • Browser-optimized bundle
  • WebAssembly acceleration
  • Streaming embeddings
  • Vector database integrations
  • Real-time similarity search
  • Edge runtime support

Made with ❤️ in Turkey 🇹🇷

Hashub Vector SDK - Powering the next generation of AI applications with Turkish excellence.