HarperFast / HarperFast/rocksdb-js
Rename `registryStatus()` to `getRegistryStatus()` for module-root naming consistency
- Dominant language
- C++
- Stars
- 21
- Forks
- 2
- Avg merge
- 2d 9h
- Merged PRs (30d)
- 36
Description
## Summary
Rename the module-root export `registryStatus()` to `getRegistryStatus()`, keeping
`registryStatus()` as a deprecated alias until the next major (v3.0.0) removes it.
## Why
The module root has two conventions for the same shape of API — a zero-argument function
that samples live native state and returns a plain object:
| Export | Convention |
|---|---|
| `registryStatus()` | bare noun |
| `getWriteBufferManagerStats()` (added in #824) | `get` prefix |
Both walk the database registry and return a snapshot. There is no principled reason for
them to read differently, and whichever one we leave alone becomes the precedent for the
next diagnostic export.
`get` wins because these calls do real work rather than reading a stored property.
`getWriteBufferManagerStats()` takes a `try_lock` on the registry and can return
`inventoryAvailable: false`; `registryStatus()` walks every descriptor. The codebase already
reserves bare nouns for cheap, stable properties (`db.compression`, `db.status`) and uses
`get*` for the sampling calls (`db.getStats()`, `db.getStat()`, `db.getEstimatedKeyCount()`).
Renaming the one non-conforming export is a smaller change than converting the new one to a
getter, and it does not put a lock-taking call behind property-access syntax.
## Proposed change
- Add `getRegistryStatus()` as the canonical name.
- Keep `registryStatus()` exported as an alias to the same function, marked
`@deprecated` in JSDoc, pointing at the new name.
- Remove the alias in v3.0.0.
- README documents `getRegistryStatus()` only. The deprecated alias does not need a
README entry; the JSDoc `@deprecated` tag is the discovery path for existing callers.
## Scope
- [ ] `src/load-binding.ts` — export `getRegistryStatus`, retain `registryStatus` as a
deprecated alias with a JSDoc `@deprecated` tag naming the replacement and the
removal version.
- [ ] `src/index.ts` — re-export both.
- [ ] `README.md` — rename the `registryStatus(): RegistryStatus` section heading and its
example, and update any anchor links to it.
- [ ] Tests — add coverage asserting the alias and the new name resolve to the same
function, so the deprecation window is enforced rather than assumed.
## Downstream consumers
`registryStatus()` is used in both Harper repos today, so the alias is what keeps this
non-breaking:
- `harper` — `dataLayer/rocksdbBackup.ts` (production path), plus three files under
`unitTests/resources/`
- `harper-pro` — `core/dataLayer/rocksdbBackup.ts` (production path), plus one file under
`core/unitTests/resources/`
Migrating those call sites is a follow-up and does not gate this change. They must be
migrated before the alias is removed in v3.0.0.
## Context
Came out of review on #824 (*Make a WriteBufferManager write stall observable*), which
introduced `getWriteBufferManagerStats()`. That PR originally exposed the function twice, as
a `RocksDatabase` static and as a module-root export; the static is being dropped in favor of
the top-level export, which is what puts the two naming conventions side by side at the
module root.
Contributor guide
Research direction
Start with the exports in src/load-binding.ts and src/index.ts, then inspect the existing registryStatus section in README.md and the project’s export tests. Add coverage for both names resolving to the same function, update the README to the new name, and verify the deprecated alias is documented with its removal version.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- node.js, typescript
- Domain
- api, backend
- Issue type
- Refactor
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 76/100