react-native-genesisdb

Embedded GenesisBlockDB for React Native (MARK XVI Phase B-3) — local-first hybrid semantic-graph engine, no server required. See docs/SPEC--MOBILE-SDK.md §B-3.

import { GenesisDB } from 'react-native-genesisdb';

const db = await GenesisDB.open(`${DocumentDirectoryPath}/genesisdb`);
const node = await db.addNode({ labels: ['Person'], props: { name: 'Ada' } });
const ctx = await db.retrieveContext(node.id, 'H1');
await db.close();

Platform status

| Platform | Status | |---|---| | Android | Working — npm install is enough. Bridges to io.github.freshair129:genesisdb-android (Phase B-2) on Maven Central, which resolves anonymously. No GitHub token, no extra repository declaration. | | iOS | Working — pod install is enough. The Swift SDK sources are vendored into this pod (ios/vendor/), so it is self-contained: no Swift Package to add in Xcode, no monorepo checkout required. See iOS integration status. |

Installation — Android

npm install react-native-genesisdb is all it takes. The native .aar this package bridges to is on Maven Central (io.github.freshair129:genesisdb-android:0.1.1), which resolves anonymously, so mavenCentral() — already in every React Native app's Gradle setup — is enough. There is nothing to add to gradle.properties.

(0.1.1 is the first version carrying the x86_64 slice the standard Android Studio emulator needs — see android/README.md.)

This used to require a GitHub personal access token. Until 0.1.1 was published to Central, the .aar was only on GitHub Packages, which demands authentication for every read even from a public repository — so every consumer had to create a read:packages PAT and put gpr.user/gpr.key in ~/.gradle/gradle.properties. If you set that up for an earlier version you can delete both lines; this package no longer declares that repository.

The Maven groupId (io.github.freshair129) differs from the Kotlin package (dev.genesisblock) because Central requires a namespace whose ownership can be proven, and genesisblock.dev belongs to an unrelated business. The two are independent identifiers — renaming the package to match would break the JNI symbols, which mangle from the class's fully-qualified name. Your imports are unaffected.

iOS integration status

GenesisDbModule.swift is real code, not a stub, and its logic mirrors the Android bridge method-for-method. pod install is now sufficient on its own — both of the pieces that previously were not are resolved:

1. ~~GenesisBlockDB.xcframework needs a prepare_command to fetch it during pod install.~~ Done (issue #125): react-native-genesisdb.podspec's prepare_command now downloads, SHA256-verifies, and unzips the v0.2.0 release's GenesisBlockDB.xcframework.zip automatically — no manual step. (An earlier version of this doc also said the podspec would need a CocoaPods Trunk publish first; that was wrong — RN autolinking's use_native_modules! picks up this podspec directly from node_modules, the same way virtually every third-party RN native module ships its iOS half, with zero Trunk publish involved.)

2. ~~The Swift package this module imports is not in the npm tarball.~~ Fixed. GenesisDbModule.swift used to do import GenesisDB / import GenesisDBTypes — products of the monorepo's ios/genesisdb package, which sits one level above this package's root and so could never be included by npm. The result was that pod install succeeded and the build then failed with "no such module 'GenesisDB'" for everyone who installed from npm; only a monorepo checkout worked, via a manual "Add Package Dependency" step in Xcode.

   CocoaPods cannot express a dependency on a Swift Package, so there was no podspec-level fix. Instead the SDK sources are now vendored into this pod at ios/vendor/, generated by scripts/vendor-rn-ios-sdk.mjs. Since s.source_files already globs ios/**/*.swift, they compile into this pod's own module — so the bridge needs no import at all, and the pod is self-contained.

   The vendoring rewrites the SPM module imports: import GenesisDBTypes is dropped (same module now) and import CGenesisDBFFI becomes import GenesisBlockDB, the Clang module the published xcframework vends via include/module.modulemap.

   Do not edit ios/vendor/*.swift — edit the originals under ../ios/genesisdb/Sources/ and re-run the script. CI job rn-ios-vendor-freshness fails if the copies drift.

What CI does and does not verify

rn-ios-vendor-freshness proves the vendored copies match their originals, and rn-ios-pod-typecheck compiles them for the iOS Simulator against the published xcframework the podspec actually downloads — the combination that a real pod install produces, and the gate that would have caught the bug above.

Still not covered: a full pod install in a real RN host app (there is none in this monorepo), and android/build.gradle's Maven resolution. That gap is why both 0.1.0 breakages shipped unnoticed.

Publishing

.github/workflows/release.yml's rn-npm-publish job publishes this package to npm (unscoped react-native-genesisdb, --tag beta) on every v* tag push, reusing the same NPM_TOKEN secret the main native-addon package publishes with (issue #125).

That job has run: [email protected] was published from the v0.2.2 tag. Re-publishing an unchanged version is correctly rejected by the registry with 403 You cannot publish over the previously published versions, so later tags no-op unless the version in package.json is bumped.

That is why this package is at 0.1.1. 0.1.0 is the version currently on npm, and it is the one with both integration breakages — the Android repository declaration and the iOS module imports were fixed on main after it shipped, so those fixes do not reach a single npm consumer until a tag push publishes 0.1.1. Bumping the version is the delivery mechanism, not bookkeeping.

Wire format

All types in src/types.ts are snake_case, matching the engine's raw serde_json output (valid_from, query_vector, ...) — not the camelCase used by the Node addon's index.d.ts (a napi-rs-only convention). See the doc comment at the top of src/types.ts for why a generic camelCase conversion layer was deliberately not built (it would corrupt keys inside the opaque props field).

Testing

src/__tests__/index.test.ts runs under plain Jest against a stubbed react-native module (src/__mocks__/react-native.ts) — no native build, no simulator/emulator, no RN runtime. Run with npm test.

The vendored iOS SDK sources are type-checked against the published xcframework by rn-ios-pod-typecheck (see "What CI does and does not verify" above). Beyond that, the android/ and ios/ native module sources are validated only by building them inside a real RN host app, which this monorepo has none of — the same host-only carve-out as the rest of the mobile SDK (see .github/workflows/mobile-build.yml).