modules/indexes-search/hyper-p2p-fulltext-lite/docs/api.md

API: hyper-p2p-fulltext-lite

Export: { HyperP2PFulltextLite, PROTOCOL }
Protocol: fulltext-lite/v1 (identifier only — no P2P wire messages)

Overview

HyperP2PFulltextLite is an in-memory inverted index for short documents. It tokenizes text (lowercase, alphanumeric tokens, stop-word removal), maintains term → document ID sets, and runs AND queries across query terms with a simple term-hit score.

The module is local-only: no Hyperswarm, no gossip. Suitable for Pear/Bare apps that need lightweight full-text search without external search engines.

Constructor

const { HyperP2PFulltextLite } = require('hyper-p2p-fulltext-lite')
const ft = new HyperP2PFulltextLite()

No constructor options. State: _docs (id → entry), _index (term → Set of doc ids), _stats.

Stop words

Built-in set: a, an, the, and, or, of, to, in, on, for, is (tokens length ≤ 1 also dropped).

Methods

tokenize(text)

• Returns: string[] of normalized tokens
• Null/undefined text: []

addDocument(id, text)

• Parameters: id (non-empty), text (any, coerced to string)
• Returns: { id, text, tokens, at }
• Behavior: Removes prior posting lists for id if re-indexing; updates inverted index; emits document
• Increments: stats.indexed

search(query)

• Returns: sorted array { id, score, snippet } where snippet is first 120 chars of document text
• Scoring: count of query terms present in document tokens
• Empty tokenized query: []
• Logic: intersection of per-term document sets (AND)
• Increments: stats.queries

getDocument(id)

Returns stored entry or null.

removeDocument(id)

Removes postings and document. Returns true if existed.

listDocuments()

Returns all document entries as an array.

getStats()

{ indexed, queries, documents, terms, protocol }

ready() / close()

ready() resolves immediately. close() clears maps and emits closed.

Events

Event	Payload
document	{ id, text, tokens, at }
closed	—

Wire messages

None. PROTOCOL is exported for registry consistency only.

Errors

assertNonEmpty on addDocument and removeDocument for empty id.

Design limits

• No stemming, no phrase queries, no OR mode
• Re-indexing a document rewrites all its term postings
• Memory scales with total tokens across documents

Example

const ft = new HyperP2PFulltextLite()
ft.addDocument('doc-1', 'hyper p2p fulltext search')
console.log(ft.search('p2p search'))
await ft.close()

Testing

npm install && npm test