knowledge-catalogue

A lightweight, dependency-free library for cataloguing, tagging, and searching knowledge entries. Ships with full TypeScript types and both ESM and CommonJS builds.

Install

npm install knowledge-catalogue

Quick start

import { KnowledgeCatalogue } from "knowledge-catalogue";

const catalogue = new KnowledgeCatalogue();

const entry = catalogue.add({
  title: "How OAuth works",
  content: "The client redirects the user to the authorization server…",
  category: "api",
  tags: ["auth", "oauth"],
});

console.log(entry.id); // auto-generated UUID

// Relevance search across title, tags and content
const hits = catalogue.search("oauth");
console.log(hits[0].entry.title); // "How OAuth works"

// Structured filtering
const apiDocs = catalogue.query({ category: "api", tags: ["auth"] });

API

new KnowledgeCatalogue(seed?)

Create a catalogue, optionally seeded with an array of NewEntryInput objects.

Mutations

| Method | Description | | --- | --- | | add(input) | Add an entry. Auto-fills id, timestamps, and normalizes tags. Returns the stored entry. | | update(id, patch) | Update the provided fields of an existing entry. Metadata is merged. | | remove(id) | Delete an entry. Returns true if one was removed. | | clear() | Remove all entries. |

Reads

| Method | Description | | --- | --- | | get(id) | Return a copy of an entry, or undefined. | | has(id) | Whether an entry exists. | | list() | All entries, newest first. | | categories() | Distinct categories, sorted. | | allTags() | Distinct tags, sorted. | | size | Number of entries (getter). |

Search

query(options) — structured filtering. All filters are ANDed:

catalogue.query({
  text: "invoice",       // case-insensitive substring on title + content
  category: "billing",
  tags: ["urgent"],      // must contain every tag
  anyTags: ["a", "b"],   // must contain at least one tag
  limit: 20,
});

search(query, limit = 10) — weighted relevance search returning { entry, score } hits sorted by score. Title matches score 5, tag matches 3, content matches 1 per term.

Persistence

const json = JSON.stringify(catalogue);          // uses toJSON()
const restored = KnowledgeCatalogue.fromJSON(JSON.parse(json));

Development

npm install
npm test          # run vitest
npm run typecheck # tsc --noEmit
npm run build     # emit ESM + CJS + .d.ts to dist/

License

MIT © Birat Datta