Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

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

Đang mở
  • Có gì không ổn?
#1,184 1 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 3 ngày

@dbisina đang làm issue này rồi.

Từ ngày 26/10/2026.

  • #1190 của @dbisina — đang mở

Đánh giá

Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
35/100
Loại issue
Lỗi
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
javascript, node.js
Lĩnh vực
backend, search

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.

Ngôn ngữ chính
JavaScript
Star
70
Fork
75
Merge trung bình
2 ngày 11 giờ
Pull request đã merge (30 ngày)
50

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của nodejs/doc-kit

Tất cả issue của nodejs/doc-kit

Issue tương tự

Thêm issue về JavaScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.