Vecal 1.0

Vecal is a browser-local vector database for applications that need private, offline-capable vector retrieval without operating a database server. IndexedDB is the durable source of truth; a dedicated module Worker owns storage, exact search, HNSW construction, and approximate search.

The 1.0.0-rc.1 line is deliberately narrow:

• Exact and self-contained TypeScript HNSW search.
• cosine, l2, and dot metrics with one higher-is-better score contract.
• Atomic batch CRUD, JSON metadata, structured top-level filters, cancellation, and build progress.
• Revision-aware multi-tab consistency and persistent HNSW snapshots.
• ESM-only output, complete TypeScript declarations, source maps, and zero runtime dependencies.

Vecal does not generate embeddings and does not include cloud sync, collections, LSH, IVF, CommonJS output, or import/export APIs.

First query

import { VectorDB, type Metadata } from 'vecal';

interface ProductMetadata extends Metadata {
    title: string;
    category: string;
}

const db = await VectorDB.open<ProductMetadata>({
    name: 'product-search',
    dimension: 3,
    metric: 'cosine',
});

await db.addMany([
    {
        id: 'shoe',
        vector: new Float32Array([0.92, 0.1, 0.04]),
        metadata: { title: 'Lightweight running shoe', category: 'shoes' },
    },
    {
        id: 'bag',
        vector: new Float32Array([0.12, 0.87, 0.44]),
        metadata: { title: 'Trail hydration pack', category: 'bags' },
    },
]);

const results = await db.search(new Float32Array([0.88, 0.16, 0.08]), {
    k: 3,
    strategy: 'exact',
    where: { category: { $eq: 'shoes' } },
});

One search API

hnsw never builds implicitly. Call ensureIndex() during an intentional indexing phase. Filtered HNSW search expands candidates and, if it cannot fill k, completes the query with exact search so filtered results are not silently lost.

Scale and environment

The intended 1.0 envelope is 50k×384-dimensional vectors or 10k×1536-dimensional vectors. This is a local database, not a replacement for a multi-user or distributed vector service. Benchmark your data, embedding distribution, and device class before shipping.

Vecal targets the latest two Chrome, Firefox, and Safari releases. Importing the package during SSR is safe, but VectorDB.open() requires browser IndexedDB and Dedicated Worker support.

Continue

1. Install and configure the Worker.
2. Build an embedding-to-search flow in the tutorial.
3. Understand scoring, Exact, and HNSW in algorithms.
4. Copy production patterns from examples.
5. Check signatures and stable errors in the API reference.