feat: add storeNames to ImportOptions for selective restore

[Atharva0506]

Addressed Issues:

Fixes #67

Screenshots/Recordings:

N/A — library-only change, no UI. Behaviour is covered by the new tests.

Before (caller has to reach into the envelope):

// couples the caller to the ExportFormat shape — a backupVersion 2 that changed
// `stores` would break this silently, with no type error
await importDB({
  dbName: 'FatePoolsDB',
  backupData: { ...backup, stores: pick(backup.stores, ['portfolioPositions']) },
  strategy: 'overwrite',
});

After:

await importDB({
  dbName: 'FatePoolsDB',
  backupData: backup,
  strategy: 'overwrite',
  storeNames: ['portfolioPositions', 'portfolioTransactions', 'portfolioCache'],
});
// -> the 6 RPC cache stores exist but are empty, so the app refetches them

Additional Notes:

What changed

• ImportOptions gains storeNames?: string[], mirroring ExportOptions.storeNames.
• importDB narrows its target-store list by that selection. Omitting it keeps the previous
  behaviour exactly, so this is backwards compatible.
• Unknown names are ignored rather than throwing, matching how exportDB treats them
  (src/core/exporter.ts). storeNames: [] restores no records.
• README gains a selective-restore example plus a note on the semantics.

Design decision worth a reviewer's eye: storeNames filters records, not schema.

openDatabaseForImport / createStoresFromSchema are deliberately untouched, so the full backup
schema is still created and a store left out of storeNames exists but is not populated (empty
under overwrite, unchanged under merge).

The alternative — filtering schema too — would mean an overwrite partial restore leaves the
unlisted stores absent entirely, so any app code touching one hits NotFoundError until it
upgrades the DB itself. It also would not match the backupData.stores workaround this replaces,
which never touched schema. For the issue's motivating case that distinction is the whole point:
the 6 RPC cache stores need to exist so they can be refetched.

Tests — 7 new cases in tests/importer.test.ts: overwrite restores only listed stores (unlisted
exist but empty); merge leaves unlisted stores' existing records untouched; omitted storeNames
restores everything; [] restores nothing but still creates the schema; unknown names ignored;
all-unknown resolves without throwing; duplicate entries do not double-insert (overwrite uses
add(), so a second pass would surface as ConstraintError). 5 of the 7 fail without the change;
the other 2 are regression guards for the default path.

Verification — npm test 63 passed (6 files), npm run lint clean, npm run build clean
(ESM + CJS + d.ts, storeNames present in the emitted declarations).

npm run format:check reports 12 files, but that is pre-existing on main — it fails identically
with this branch stashed, and it flags files this PR does not touch
(src/core/exporter.ts, src/core/migrations.ts, src/utils/ssr.ts, …). Running Prettier against
the three changed files with the project config shows zero deviations in src/types/index.ts
and tests/importer.test.ts, and in src/core/importer.ts every deviation sits above line 254 —
all of it pre-existing code, none in the new region. Reformatting the repo here would bury the
feature diff, so I left it out; happy to fix it in a separate style: PR if you want.

Version — VERSION is intentionally untouched, since a push to it on main triggers tag +
release + npm publish via version-release.yml. This is an additive optional field, so it is a
minor bump: 1.0.1 → 1.1.0 whenever you want to cut the release (possibly batching #68).

Checklist

• My code follows the project's code style and conventions
• I have made corresponding changes to the documentation
• My changes generate no new warnings or errors
• I have joined the Discord server and I will share a link to this PR with the project maintainers there
• I have read the Contributing Guidelines

AI Assistance Disclosure

Written with Claude Code, model claude-opus-5[1m] (Claude Opus 5, 1M context).
The design decision above (records-vs-schema filtering) was reviewed and chosen by me, and the
build, lint, and test results were verified locally before opening this PR.

Summary by CodeRabbit

• New Features

  • Added selective database restore using an optional list of store names.
  • Database schemas continue to be created for all backed-up stores, while records are restored only for selected stores.
  • Supports overwrite and merge behavior, including empty selections and unknown store names.

• Documentation

  • Added usage guidance and examples for selective restores.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 4a0d894c-82ab-4e34-9e95-9b86d2ca4987

📥 Commits

Reviewing files that changed from the base of the PR and between 47b4e74 and e0c5842.

📒 Files selected for processing (5)

• README.md
• checklist-status.json
• src/core/importer.ts
• src/types/index.ts
• tests/importer.test.ts

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

Walkthrough

importDB now accepts storeNames to restore records from selected stores. It still creates the full backup schema. Documentation and tests cover overwrite, merge, empty, unknown, duplicate, and omitted selections.

Changes

Selective restore

Layer / File(s)	Summary
Import contract and filtering src/types/index.ts, src/core/importer.ts, README.md	Adds storeNames?: string[] to ImportOptions. importDB filters restored records by selected store names while creating all backup schemas.
Selective restore validation tests/importer.test.ts, checklist-status.json	Tests selective overwrite and merge behavior, empty and unknown selections, duplicate names, omitted options, schema creation, and the updated checklist timestamp.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to e0c58

The PR adds optional selective store restoration while preserving existing behavior when omitted; no actionable merge-blocking risk remains beyond normal checks and review.

Suggested labels: Typescript Lang

Poem

I’m a rabbit restoring one store at a time,
While every schema grows in a tidy line.
Empty lists leave records asleep,
Merge keeps old data safely deep.
Unknown names hop past the door,
And selected records land once more.

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The feature code, documentation, and tests are in scope. The checklist-status.json timestamp update is unrelated to issue #67 and appears to be an out-of-scope administrative change.	Remove the unrelated checklist-status.json timestamp change, or provide explicit scope justification for including it.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: adding storeNames to ImportOptions for selective restore.
Linked Issues check	✅ Passed	The implementation satisfies issue #67. It adds the optional storeNames property, restores only selected stores, preserves default behavior when omitted, supports empty and unknown selections, and k…

Full details: Linked Issues check

Explanation

The implementation satisfies issue #67. It adds the optional storeNames property, restores only selected stores, preserves default behavior when omitted, supports empty and unknown selections, and keeps schema creation unchanged.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

	Messages
📖	### ⚠️ PR Template Check These are non-blocking, but please fix: Some required checklist items are not completed: My PR addresses a single issue

Generated by 🚫 dangerJS against 89c4f46