Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

orama-db: `orama-db.json` changes on every build

Aberta
  • Algo errado?
#1,184 1 comentário 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 3 dias

@dbisina já está trabalhando nisso.

Desde 26/10/2026.

  • #1190 de @dbisina — aberto

Avaliação

Dificuldade
2/5
Tempo estimado
1-3 horas
Facilidade para iniciantes
35/100
Tipo de issue
Bug
Clareza
Claramente especificada
Status de atividade
Estagnada
Stack de tecnologia
javascript, node.js
Domínio
backend, search

Direção de pesquisa

Start with packages/react/src/orama-db/generate.mjs: read how it builds documents, calls insertMultiple, and saves the index; the issue also points to useOrama.mjs to check how search uses results. Add stable ids and sort the flattened documents by href, then create the suggested generator tests for repeatability, input order, and search behavior. Run node --run test and confirm the generated output is stable; pull request #1190 is already open against this issue.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

good first issue help wanted Web Generator

Running a build twice on the same docs gives two different orama-db.json files, for two reasons:

  1. Timestamp-based ids. The orama-db generator inserts documents without an id, so Orama 3.x makes one up from the current time and a counter (e.g. 20003290-1). That id is saved in the index (internalDocumentIDStore.internalIdToId), so the file changes on every build.
  2. Insertion order. Orama's saved index follows the order documents were inserted, and the generator's input order can change between builds (see #1183).

The search index is several MB, so a file that changes on every deploy wastes caching, and CI can't compare it byte for byte.

Where to look

  • packages/react/src/orama-db/generate.mjs:27-44: builds the documents (title, description, href, siteSection) with no id, in input order.
  • The same file, line 40: href (${entry.path}.html#${entry.heading.data.slug}), which makes a natural stable id.
  • The same file, line 47: insertMultiple(db, documents); lines 49-56: save(db) is written to orama-db.json.
  • packages/react/src/html/ui/hooks/useOrama.mjs:26-41: the website loads the saved index and searches it. It doesn't depend on the id format, and results are rendered from hit.document.

How to reproduce

From packages/react (where @orama/orama resolves), save this as repro.mjs and run node repro.mjs a few times:

import { createHash } from 'node:crypto';
import { create, insertMultiple, save } from '@orama/orama';

const docs = [
  { title: 'fs', description: 'File system', href: 'fs.html#fs', siteSection: 'fs' },
  { title: 'fs > readFile', description: 'Reads a file', href: 'fs.html#readfile', siteSection: 'fs' },
];

const db = create({
  schema: { title: 'string', description: 'string', href: 'string', siteSection: 'string' },
});

await insertMultiple(db, docs); // try: docs.map(doc => ({ id: doc.href, ...doc }))

const out = JSON.stringify(save(db));
console.log(createHash('sha256').update(out).digest('hex').slice(0, 16));

Each run prints a different hash. With the commented id: doc.href line, every run prints the same one, until you reverse docs, which changes it again.

Suggested approach

Only packages/react/src/orama-db/generate.mjs needs to change:

  1. Add id: href to each document (Orama requires string ids, and href is one).
  2. Sort the flattened documents by href before inserting them, comparing with < and > (or localeCompare(..., 'en')) so the order doesn't depend on the machine's locale.

Keep the existing flatMap as it is, and sort its result, not the input: buildHierarchicalTitle walks each module's headings in document order to build titles like "Class > Method".

How to test

There's no generator test for orama-db yet. Create packages/react/src/orama-db/__tests__/generate.test.mjs, setting up the config like llms-txt-full/__tests__/generate.test.mjs does (setConfig({ target: ['orama-db'] }), then set output to undefined so generate() just returns the saved index). With a few fake metadata entries from two modules, test that:

  1. Two runs give the same output: compare the JSON.stringify of two generate() results. This already fails today within a single process.
  2. Input order doesn't matter: put one module's entries before the other's, keeping each module's own entries in order, and compare.
  3. Search still works: load() the result into create({ schema: {} }), search() for a title word, and check hits[0].document.href.

Run everything with node --run test.

Things to watch out for

  • Ids must be unique, or Orama throws DOCUMENT_ALREADY_EXISTS and the build fails. Slugs are deduplicated per file, so hrefs should be unique. If the full Node.js docs build throws anyway, point out the duplicate in your PR rather than going back to automatic ids.
  • save() doesn't include the database's own id, so that one doesn't matter.
  • The output is only identical for the same @orama/orama version; a dependency update can still change it.

Getting started

New to doc-kit? CONTRIBUTING.md covers setup, running the tests and adding a changeset (node --run changeset, a patch for @doc-kit/generator-react). Leave a comment here if you'd like to take it on.

Linguagem predominante
JavaScript
Estrelas
70
Forks
75
Merge médio
2d 11h
PRs com merge (30d)
50

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de nodejs/doc-kit

Todas as issues de nodejs/doc-kit

Issues semelhantes

Mais issues de JavaScript

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.