Hypertill DB

Hypertill DB is the published HelaPoint-maintained fork of WatermelonDB. It keeps the same local-first database architecture, but the package identity, docs, and mobile example app now ship under the Hypertill name.

What 0.0.4 already gives you

• The live docs site: https://db.hypertill.com/
• The npm package: @hypertill/db
• Expo SDK 54+ support through the built-in package plugin
• Expo plugin auto-patching for Babel decorators/class-field transforms
• React helpers: DatabaseProvider, useDatabase, withObservables
• Auto-generated React query hooks via hooks.use<Model> and generic hooks.useModels
• Reserved Model getters for createdAt, updatedAt, and deletedAt
• SQLite adapters for iOS, Android, and Node.js
• LokiJS support for browser-based usage
• A TypeScript Expo reference app for books, chapters, book notes, and chapter notes

Start here

1. Open the docs site: https://db.hypertill.com/
2. Install the package: Installation guide
3. Set up schema and models: Setup guide
4. Connect React screens: Connecting Components
5. Review the working mobile reference: expo-hypertillDB-example

Current React guidance in 0.0.4

• Put DatabaseProvider at the app root once.
• Use hooks for reactive reads (hooks.use<Model>, hooks.use<Models>, hooks.use<Models>Advanced).
• Use useDatabase for writes, screen actions, and imperative lookups.
• withObservables is still supported for advanced or highly custom reactive compositions.

Example hook usage:

import { hooks } from '@hypertill/db/react'

const { data: notes, loading } = hooks.useNotes({ search: 'hello', timeframe: '7d' })
const { data: note } = hooks.useNote(noteId)
const { data: advanced } = hooks.useNotesAdvanced({
  q: (Q) => [Q.where('title', Q.like('%hello%'))],
})

Database defaults (IDs + timestamps)

By default, Database now auto-configures:

• Record IDs as UUIDv4 (Supabase-compatible format)
• Timestamps in epoch+timezone mode, with createPlatformAdapter() injecting created_at, updated_at, deleted_at, and *_tz metadata columns

Use zero config:

const database = new Database({
  adapter,
  modelClasses,
})

To remove platform adapter boilerplate (database.web.ts + database.native.ts), you can now use:

import { createPlatformAdapter } from '@hypertill/db'

const adapter = createPlatformAdapter({ schema, dbName: 'app-db' })
// web => LokiJSAdapter, native/node => SQLiteAdapter

Override only when needed:

const database = new Database({
  adapter,
  modelClasses,
  recordIds: { strategy: 'uuidv7' }, // default: uuidv4
  timestamps: {
    mode: 'epoch+timezone', // or 'epoch'
    timezoneSource: 'device', // or 'utc' or explicit IANA string
  },
})

Core package surface

The current package exports the following primitives:

• Database
• Collection
• Model
• Query
• Relation
• schema helpers such as appSchema() and tableSchema()

What Hypertill DB is good at

• Offline-first mobile apps with real local data models
• Large local datasets that should stay in SQLite until queried
• Apps that need explicit write boundaries and predictable sync handoff
• Teams that want a published Expo-compatible package instead of a private patch

Practical reference app

The external Expo example repo is here:

• expo-hypertillDB-example

It uses TypeScript, separate screens for books, chapters, and notes, and the published @hypertill/db package.

Contributing

Contributions to the fork should preserve API quality, platform compatibility, and clear docs. See CONTRIBUTING for setup, testing, and release workflow details.

Upstream lineage

The upstream project was originally created by Nozbe and led by Radek Pietruszewski.

The Hypertill DB fork is maintained by HelaPoint.

See all contributors.

Hypertill DB is available under the MIT license. See the LICENSE file for more info.