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
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-vectorFor TypeScript projects (types included):
npm install hashub-vectorFor 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 testRun with coverage:
npm run test:coverageRun 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
- Documentation: GitHub Repository
- Issues: GitHub Issues
- Email: support@hashub.dev
- NPM: hashub-vector
🚀 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.