@geenius/db

Multi-provider database adapters for the Geenius ecosystem.

Overview

@geenius/db is the concrete database runtime for the Geenius ecosystem. It re-exports the framework-agnostic DbAdapter contract from @geenius/adapters, owns the four launch provider factories, and ships the in-scope React, SolidJS, and React Native framework bindings. Applications keep the same CRUD-facing API while swapping between Convex, Neon, Cloudflare KV, and memory providers. The package also ships a small cross-variant review surface for Storybook, docs, and operator-facing status panels, including a provider-aware DbCollectionPage export in every UI variant.

Installation

pnpm add @geenius/db

Install framework and backend peers only for the variants you use:

pnpm add react react-dom              # React bindings
pnpm add solid-js                     # SolidJS bindings
pnpm add react-native                 # React Native binding
pnpm add convex                       # Convex backend
pnpm add @neondatabase/serverless          # Neon backend

Cloudflare KV uses the Worker-provided KVNamespace; memory has no runtime peer. Drizzle, Prisma, and Kysely are BYODB overlays for app-owned adapters, not launch dependencies for @geenius/db/neon.

Import Examples

Root shared helpers:

import type { DbAdapter } from '@geenius/db'
import {
  DbError,
  createCloudflareKVDbAdapter,
  createConvexDbAdapter,
  createMemoryDbAdapter,
  createNeonDbAdapter,
} from '@geenius/db'

React:

import { DbCollectionPage, DbPill, DbProvider, DbStack, DbSurface, useDb } from '@geenius/db/react'

React CSS:

import { DbCollectionPage, DbPill, DbProvider, useDb } from '@geenius/db/react-css'
import '@geenius/db/react-css/styles.css'

SolidJS:

import { DbCollectionPage, DbPill, DbProvider, DbSurface, createDb } from '@geenius/db/solidjs'

SolidJS CSS:

import { DbCollectionPage, DbProvider, DbSurface, createDb } from '@geenius/db/solidjs-css'
import '@geenius/db/solidjs-css/styles.css'

React Native:

import { DbCollectionPage, DbProvider, useDb } from '@geenius/db/react-native'

Convex:

import { schema, queries, mutations } from '@geenius/db/convex'
import { api as dbApi } from '@geenius/db/convex/api'

Neon:

import { createNeonDiagnosticsLogger, neonDiagnosticsStatements } from '@geenius/db/neon'

Cloudflare KV:

import {
  CLOUDFLARE_KV_CAPABILITIES,
  buildKVIndexKey,
  buildKVRecordKey,
  createMockKVNamespace,
} from '@geenius/db/cloudflareKV'

const recordKey = buildKVRecordKey('users', 'user_1', 'geenius:')
const indexKey = buildKVIndexKey('users', 'geenius:')
const kv = createMockKVNamespace()
await kv.put(recordKey, JSON.stringify({ id: 'user_1', name: 'Avery' }))
await kv.put(indexKey, JSON.stringify(['user_1']))

Memory:

import {
  MEMORY_CAPABILITIES,
  MEMORY_DEFAULT_COLLECTIONS,
  MEMORY_PROVIDER_ID,
  MEMORY_PROVIDER_LABEL,
  createMemorySeed,
  mergeMemorySeeds,
} from '@geenius/db/memory'

const seed = mergeMemorySeeds(
  createMemorySeed('users', [{ id: 'user_1', name: 'Avery' }]),
  createMemorySeed('projects', [{ id: 'project_1', name: 'Launch' }]),
)

const memoryProvider = {
  id: MEMORY_PROVIDER_ID,
  label: MEMORY_PROVIDER_LABEL,
  collections: MEMORY_DEFAULT_COLLECTIONS,
  capabilities: MEMORY_CAPABILITIES,
  seed,
}

API Summary

| Subpath | Purpose | | --- | --- | | @geenius/db | Shared adapter types, DbError classes, and the four provider factories. | | @geenius/db/convex | Convex diagnostics schema, queries, mutations, and component config. | | @geenius/db/convex/api | Generated Convex api, internal, and components handles. | | @geenius/db/neon | Neon migrations, diagnostics schema metadata, SQL statement helpers, and diagnostics logger. | | @geenius/db/cloudflareKV | Cloudflare KV provider capabilities, key helpers, and mock namespace utilities. | | @geenius/db/memory | Memory provider id/label/default collections, capability descriptor, and deterministic seed helpers. | | @geenius/db/react | React DbProvider, useDb, useDbOptional, review components, and DbCollectionPage. | | @geenius/db/react-css | React API parity with vanilla CSS classes and styles.css. | | @geenius/db/react-native | React Native DbProvider, useDb, native review components, and DbCollectionPage. | | @geenius/db/solidjs | SolidJS DbProvider, createDb, createDbOptional, review components, and DbCollectionPage. | | @geenius/db/solidjs-css | SolidJS API parity with vanilla CSS classes and styles.css. |

Deferred compatibility subpaths for the remaining UI libraries are still present in the export map, but this run marks them inScope: false and excludes them from build, test, Storybook, visual, and support-loop evidence: @geenius/db/react-shadcn, @geenius/db/react-ant, @geenius/db/react-chakra, @geenius/db/react-mui, @geenius/db/react-mantine, @geenius/db/react-heroui, @geenius/db/react-daisyui, @geenius/db/solidjs-ark, @geenius/db/solidjs-kobalte, and @geenius/db/solidjs-solidui.

Current Variant Matrix

| Axis | In scope | Notes | | --- | --- | --- | | DB providers | convex, neon, cloudflareKV, memory | Cloudflare KV is key/value plus TTL only; memory is dev/test oriented. | | Framework bindings | react, react-css, solidjs, solidjs-css, react-native | CSS variants require their stylesheet subpath import; React Native uses StyleSheet and native primitives. | | Deferred UI bindings | react-shadcn, react-ant, react-chakra, react-mui, react-mantine, react-heroui, react-daisyui, solidjs-ark, solidjs-kobalte, solidjs-solidui | Kept on disk with inScope: false; do not treat them as support-loop green cells. |

Cloudflare KV supports key/value CRUD, TTL, and bounded collection-index scans. It does not claim SQL, joins, or relational transactions; those limitations are documented in its exported option and unsupported-operation types.

Use keyPrefix and recordTtlSeconds for new Cloudflare KV adapters:

const db = createCloudflareKVDbAdapter(env.GEENIUS_KV, {
  keyPrefix: 'geenius:',
  recordTtlSeconds: 3600,
})

Use the helper subpath when tests or diagnostics need to inspect adapter keys without depending on private internals:

import {
  buildKVIndexKey,
  buildKVRecordKey,
  createMockKVNamespace,
} from '@geenius/db/cloudflareKV'

const kv = createMockKVNamespace()
const recordKey = buildKVRecordKey('users', 'user_1', 'geenius:')
const indexKey = buildKVIndexKey('users', 'geenius:')

await kv.put(recordKey, JSON.stringify({ id: 'user_1', name: 'Avery' }))
await kv.put(indexKey, JSON.stringify(['user_1']))

The older prefix and defaultTtlSeconds names remain compatibility aliases.

Variant Styling

The standard React and SolidJS variants expose the published review components through Tailwind utility classes backed by shared --gn-* design tokens from @geenius/tokens. The CSS variants mirror the same component names and semantics in vanilla CSS. Low-level styling helpers such as cn and cx, class-name helper types, and Storybook story exports are variant-local implementation details, not portable consumer imports.

The CSS variants ship static vanilla CSS alongside their JavaScript entrypoints. Import the stylesheet subpath for the CSS runtime you use:

import '@geenius/db/react-css/styles.css'
import '@geenius/db/solidjs-css/styles.css'

Basic Usage

import { createMemoryDbAdapter } from '@geenius/db'
import { DbPill, DbProvider, DbStack, DbSurface, useDb } from '@geenius/db/react'

const db = createMemoryDbAdapter()

export function App(): JSX.Element {
  return (
    <DbProvider db={db}>
      <UsersPanel />
    </DbProvider>
  )
}

export function UsersPanel(): JSX.Element {
  const db = useDb()

  void db.list('users')

  return (
    <DbSurface
      eyebrow="Adapter"
      title="Users"
      summary="Records loaded through the shared DbAdapter contract."
    >
      <DbStack>
        <DbPill tone="success">Connected</DbPill>
        <div>Users loaded through the shared DbAdapter contract.</div>
      </DbStack>
    </DbSurface>
  )
}

Collection Page

The UI variants also export DbCollectionPage, a ready-made collection review surface that loads records through the active provider and renders them with the published review components:

import { createMemoryDbAdapter } from '@geenius/db'
import { DbCollectionPage, DbProvider } from '@geenius/db/react'

const db = createMemoryDbAdapter()

export function UsersRoute(): JSX.Element {
  return (
    <DbProvider db={db}>
      <DbCollectionPage collection="users" />
    </DbProvider>
  )
}

Convex Codegen

@geenius/db publishes the geenius-convex-codegen CLI used by package and app Convex variants to generate typed _generated/ helpers before bundling:

pnpm exec geenius-convex-codegen

The published Convex package also exposes the generated API bridge at @geenius/db/convex/api so consuming apps can reference packaged functions through a stable subpath export.

Storybook and Review Surface

This package maintains review apps for the in-scope UI variants. The apps import only published subpaths, so parity, provider context, and packaging regressions are visible before release. Maintainers can preview or build a variant with:

pnpm storybook:react
pnpm storybook:react:build
pnpm storybook:react-css
pnpm storybook:solidjs
pnpm storybook:solidjs-css
pnpm test:storybook

Shared checks:

• pnpm test:conventions
• pnpm test:storybook:build
• pnpm test:storybook-parity

Testing

PR gates run through pnpm test:gauntlet: Biome, app lint, publint, type-check, unit/root contracts, packed import smoke, bundle budgets, supply-chain audit, license checks, and SBOM emission.

Nightly and release gates use pnpm test:all, which adds Storybook, DB conformance and migrations, Playwright e2e, axe/keyboard/focus accessibility, default-on visual regression, performance smoke, and coverage reporting.

Visual baselines are updated only after review:

pnpm test:visual -- --update-snapshots

Mutation testing is intentionally separate because it is slow:

pnpm test:mutation

Contributing tests

variants.json is the single source of truth for launch DB providers, UI variants, harnesses, Storybook apps, coverage thresholds, and bundle budgets. When adding or changing a variant, update variants.json first, then add the variant package/app, run node scripts/_pnpm-filters.mjs build --print, and verify that pnpm test:gauntlet still reaches the new public subpath.

Keep tests on public contracts:

• Unit tests live with the sub-package source.
• Cross-variant drift tests live in __tests__/.
• Convention tests live in __tests__/conventions/ and enforce workspace deps, tsconfig.build.json, public-surface, Storybook app shape, and ecosystem dependency rules.
• Playwright specs live in e2e/ and select variants through the generated matrix.
• Packed smoke tests must import from the tarball, not workspace internals.

License

FSL-1.1-Apache-2.0 for the free tier. Commercial usage is governed by the repository license terms in LICENSE.