polypack

Generic property graph engine with vector similarity search, edge ownership semantics, relational queries, and real-time sync. Runs in Node.js and the browser with pluggable persistence (in-memory, filesystem, or OPFS).

Install

npm install @0xx0lostcause0xx0/polypack

React is an optional peer dependency and is only required when importing from @0xx0lostcause0xx0/polypack/react.

Python and Rust bindings over the same core are published separately:

pip install polypack-db

cargo add polypack-core

Releases

• npm package: @0xx0lostcause0xx0/polypack is the installable TypeScript/JavaScript distribution for Node.js and browser build tooling. @0xx0lostcause0xx0/polypack-native provides NAPI-RS bindings to the native VectorIndex/HNSWIndex.
• PyPI package: polypack-db is the Python distribution, built with maturin/PyO3 over the same Rust core.
• crates.io package: polypack-core is the portable Rust core (property graph, vector search, persistence) underlying the TypeScript native addon and the Python bindings.
• GitHub releases: release notes, source archives, and tags are published from the repository. The current source release is v2.4.5.

Stable GitHub releases run the complete test, build, export, and package checks before the corresponding packages are submitted to npm, PyPI, and crates.io with provenance/trusted publishing. All three ecosystems are version-locked together. See the changelog for breaking changes and migration notes.

Features

• Property graph — typed nodes and edges with arbitrary data payloads
• LRU working set — 50K loaded-node limit by default, with explicit restoration from persistence
• Vector similarity — cosine, euclidean, or pluggable distance functions
• Pluggable text embeddings — supply any local or hosted model, with a dependency-free 384-dimensional feature-hash provider included by default
• Fluent query builder — filter by type/attribute/edge/range, BFS traversal, vector similarity
• Relational extensions — pluck, aggregate, groupAggregate, join, groupByVector (clustering)
• Edge ownership — owned (cascade delete), shared (orphan detection), reference (no-op)
• Reactive — RxJS change events, batching, React hooks
• Pluggable persistence — MemoryAdapter, BinaryStoreAdapter (MessagePack + WAL), build your own
• Persisted queries — asynchronous filtering and similarity across the full backing store
• Real-time sync — acknowledgements, retry, deduplication, reconnect recovery, and echo suppression

Quick start

import { PolyGraph, MemoryAdapter } from '@0xx0lostcause0xx0/polypack'

const graph = new PolyGraph()

// Add nodes with vectors
graph.addNode({
  id: 'doc_1',
  type: 'document',
  data: { title: 'Quantum Computing' },
  vector: new Float64Array([0.95, 0.20, 0.10]),
  insertedAt: Date.now(),
  updatedAt: Date.now(),
})

// Or generate vectors from text with the default model-free provider
await graph.addNodeWithEmbedding({
  id: 'doc-2',
  type: 'document',
  data: { title: 'Graph search' },
  insertedAt: Date.now(),
  updatedAt: Date.now(),
}, 'Property graphs with vector similarity search')

const textMatches = await graph.queryText('semantic graph search', 0.1, 10)
textMatches.toArray()

// Search by similarity
graph.query()
  .whereNodeType('document')
  .similarTo([0.90, 0.30, 0.10], 0.5, 5)
  .toArray()

// Traverse edges
graph.query()
  .where('title', 'Quantum Computing')
  .traverse('REFERENCES', 3, 'out')
  .toArray()

// Aggregate
graph.query()
  .whereNodeType('book')
  .aggregate('price', 'avg')

// Group by vector cluster
graph.query()
  .whereNodeType('product')
  .groupByVector(
    [{ key: 'electronics', centroid: [0.9, 0.1] }],
    'price', 'avg', 0.4,
  )

Packages

| Subpath | Contents | |---------|----------| | @0xx0lostcause0xx0/polypack | Core: PolyGraph, VectorIndex, GraphQuery, MemoryAdapter | | @0xx0lostcause0xx0/polypack/persistence | Platform-neutral persistence: adapters, FileIO types | | @0xx0lostcause0xx0/polypack/persistence/node | BinaryStoreAdapter + NodeFileIO for the filesystem | | @0xx0lostcause0xx0/polypack/persistence/opfs | BinaryStoreAdapter + OPFSFileIO for the browser | | @0xx0lostcause0xx0/polypack/react | React hooks: useGraphQuery, useLiveQuery | | @0xx0lostcause0xx0/polypack/sync | Sync layer: OpLog, SyncAdapter, SyncClient, SyncServer | | @0xx0lostcause0xx0/polypack-native | Separate package: NAPI-RS bindings for native VectorIndex/HNSWIndex over the Rust core | | polypack-db (PyPI) | Separate package: PyO3/maturin bindings exposing PolyGraph, GraphQuery, and vector indexes to Python — see python/README.md | | polypack-core (crates.io) | Separate package: the portable Rust core (property graph, vector search, persistence) shared by the TypeScript native addon and the Python bindings |

See the complete API reference, including persistence, React, sync, lifecycle, ownership, and error contracts.

Requirements

• Node.js 18 or newer when used in Node.js.
• A browser with the File System Access API (OPFS) when using @0xx0lostcause0xx0/polypack/persistence/opfs.
• Equal vector dimensions for similarity operations; mismatches throw RangeError.

Polypack is distributed as native ES modules.

Contributing and security

See CONTRIBUTING.md for development instructions. Please report vulnerabilities according to SECURITY.md.

License

MIT