modules/indexes-search/hyper-p2p-inverted-index/docs/api.md

API: hyper-p2p-inverted-index

Export: { HyperP2PInvertedIndex, PROTOCOL }
Protocol: inverted-index/v1

Overview

HyperP2PInvertedIndex maps normalized terms to document IDs and mirrors document → term sets locally. With a Hyperswarm topic, add/remove operations gossip as term-index-sync so peers converge on the same inverted postings without shipping full index snapshots.

Constructor

const { HyperP2PInvertedIndex } = require('hyper-p2p-inverted-index')
const idx = new HyperP2PInvertedIndex(opts)

Option	Type	Default	Description
topic	string | Buffer | null	null	Swarm topic; gossip active after ready()
keyPair	KeyPair	new key pair	Swarm identity; peerHex on gossip

Term normalization

normalizeTerm(term) → lowercase trimmed string. Empty tokens dropped on index.

Methods

index(docId, terms)

• Parameters: docId (non-empty), terms (array of strings)
• Returns: { docId, terms: normalized[] }
• Gossip: For each new term on this doc, sends { type: 'term-index-sync', op: 'add', term, docId, peer, at }
• Emits: index
• Increments: stats.indexed

search(term)

• Returns: sorted doc IDs for normalized term, or []
• Increments: stats.queries

removeDoc(docId)

Removes all term postings for document; gossips op: 'remove' per term. Emits remove. Returns false if unknown doc.

listTerms()

Sorted list of indexed terms.

docCount()

Number of documents in _docs.

getStats()

{
  indexed, removed, queries, gossipIn, gossipOut,
  terms, docs, protocol
}

ready() / close()

Joins swarm when topic set. close() clears maps and destroys swarm.

Gossip handler _onGossip

Accepts only type === 'term-index-sync'.

op	Effect	Event
add	Add docId to term set; update _docs	remote-index
remove	Remove posting; trim _docs term set	remote-remove

Events

Event	Payload
index	{ docId, terms }
remove	{ docId }
remote-index	{ term, docId, peer }
remote-remove	{ term, docId, peer }
closed	—

Wire messages (summary)

type	fields
term-index-sync	op (add | remove), term, docId, peer, at

Errors

assertNonEmpty on index and removeDoc. Gossip ignored when _peerMsgs not ready.

Usage pattern

const idx = new HyperP2PInvertedIndex({ topic: process.argv[2] })
await idx.ready()
idx.index('doc-1', ['hyper', 'p2p', 'index'])
console.log(idx.search('p2p'))
await idx.close()

Comparison to fulltext-lite

Feature	inverted-index	fulltext-lite
P2P sync	yes (term-index-sync)	no
Document body	terms only	full text + snippets
Query	single term	multi-term AND

Testing

npm install && npm test