rfdb-metadata-gotchas

name: rfdb-metadata-gotchas description: | Fix silent metadata issues in RFDB node storage. Covers two traps: (1) metadata flattening — nested metadata fields become top-level after serialization, so node.metadata.field is undefined but node.field works. (2) reserved keys — fields named "type", "id", "name", "file", "exported" are silently stripped from metadata by _parseNode() to prevent overwriting top-level node fields. author: Claude Code version: 2.0.0 date: 2026-05-03

RFDB Metadata Gotchas

Trap 1: Metadata Flattening

RFDB serialization flattens nested metadata to the node's top level.

What happens:

1. Analyzer stores: {id, type, file, metadata: {handlerStart: 93}}
2. client.addNodes serializes metadata as JSON string
3. _parseNode deserializes and spreads onto top level
4. After retrieval: handlerStart is at TOP LEVEL, not nested

Wrong:

const handlerStart = route.metadata?.handlerStart;  // undefined!

Correct:

const handlerStart = route.handlerStart;  // 93

TypeScript interfaces — define custom fields at top level:

interface HttpRouteNode extends BaseNodeRecord {
  type: 'http:route';
  handlerStart?: number;  // top level, not nested under metadata
}

Trap 2: Reserved Keys (Silent Data Loss)

_parseNode() strips these keys from metadata to prevent overwriting top-level node fields:

Use non-colliding names:

Detection

1. console.log(JSON.stringify(node, null, 2)) — check if field is at top level
2. Raw wire format: backend._client.getAllNodes() returns WireNode with metadata as JSON string
3. If field appears in raw wire but not in parsed node → reserved key stripping

Notes

• Applies to ALL custom fields on nodes, not just metadata
• Both TestDatabaseBackend and RFDBServerBackend have this behavior
• If you need truly nested data, store it as a JSON string that doesn't get auto-parsed