@tcbs/data-realm

Realm adapter package for projects using @tcbs/core.

@tcbs/data-realm is the data-layer bridge between your app architecture and Realm storage. It is designed for teams following a layered setup:

• App Layer (navigation + orchestration)
• Module Layer (feature logic)
• Core Layer (contracts and infrastructure)
• Shared Layer (reusable UI)
• Data Layer (Realm implementation)

Table of Contents

• Why This Package Exists
• Package Status
• Requirements
• Installation
• Quick Start
• Tutorial: Wire Into a Layered App
• Integration With @tcbs/realm-inspector
• Best Practices
• Production Checklist
• Troubleshooting
• Credits
• Support

Why This Package Exists

Most teams want Realm speed and offline capability without leaking storage SDK details into business/UI layers.

This package helps you keep boundaries clean:

• @tcbs/core owns contracts
• @tcbs/data-realm owns Realm integration details
• modules/services stay storage-agnostic

Package Status

Current version (0.1.x) is a foundational release.

What is available now:

• RealmDataAdapter with lifecycle contract (connect, disconnect)
• RealmAdapterConfig (path, schemaVersion)
• clean dependency alignment with @tcbs/core

What is expected in upcoming releases:

• built-in repository utilities
• schema helpers and migrations toolkit
• transaction and query helpers
• optional encryption key helpers

This README gives you a production-minded way to adopt the package today while remaining forward-compatible.

Requirements

• Node.js >=18
• React Native project (or Node runtime where realm is supported)
• @tcbs/core contracts in your architecture

Installation

npm i @tcbs/core @tcbs/data-realm realm

Quick Start

1) Create the adapter

import { RealmDataAdapter } from "@tcbs/data-realm";

const adapter = new RealmDataAdapter({
	path: "default.realm",
	schemaVersion: 1,
});

2) Open the data layer during app bootstrap

await adapter.connect();

3) Close gracefully on app shutdown/test teardown

await adapter.disconnect();

Tutorial: Wire Into a Layered App

This section shows a practical integration style for existing projects.

Step 1: Keep contracts in @tcbs/core

Define your domain model/repository contract in your app or shared contract module:

import type { Repository } from "@tcbs/core";

export type Note = {
	id: string;
	title: string;
	content: string;
	createdAt: string;
};

export type NoteRepository = Repository<Note, string>;

Step 2: Initialize RealmDataAdapter in Data Layer

import { RealmDataAdapter } from "@tcbs/data-realm";

export const dataAdapter = new RealmDataAdapter({
	path: "default.realm",
	schemaVersion: 1,
});

Step 3: Bootstrap centrally

import { dataAdapter } from "./data/adapter";

export async function bootstrapApp() {
	await dataAdapter.connect();
	// initialize your repositories/services after connect
}

Step 4: Keep Realm usage behind repositories

Do not access Realm directly from screens or UI components.

Recommended flow:

1. Screen -> Service
2. Service -> Repository interface (@tcbs/core)
3. Repository implementation -> Realm operations

Integration With @tcbs/realm-inspector

Use inspector during development to validate schema/records quickly.

Install dev tooling:

npm i -D @tcbs/realm-inspector

Add a script:

{
	"scripts": {
		"tcbs:inspect": "tcbs-realm-inspector"
	}
}

Open inspector:

npm run tcbs:inspect

Best Practices

1. Keep @tcbs/core as the source of truth for interfaces and contracts.
2. Keep all direct Realm operations in the Data Layer only.
3. Version schema changes carefully and document migrations.
4. Avoid leaking Realm-specific objects into Module/UI layers.
5. Use one adapter instance per app process unless you have a specific isolation strategy.
6. Close adapter connections in tests and app teardown hooks.
7. For sensitive workloads, plan encryption key management early.
8. Pair with @tcbs/realm-inspector in development, not production builds.

Production Checklist

• [ ] Contracts are defined in @tcbs/core
• [ ] Data access is repository-driven
• [ ] No direct Realm calls in screens/components
• [ ] Schema versioning strategy documented
• [ ] Error handling/logging around adapter lifecycle
• [ ] Inspector disabled in production environments
• [ ] Backup and restore behavior tested

Troubleshooting

Cannot find module 'realm'

Install realm in the consuming project:

npm i realm

Adapter connects but app data flow is inconsistent

• Verify app bootstrap waits for connect() before repository usage.
• Ensure only one lifecycle owner initializes/disposes the adapter.

Existing app migration concerns

• Start by wrapping old Realm calls behind repository interfaces.
• Migrate feature-by-feature instead of rewriting the full app.

Credits

This package stands on top of these key dependencies and ideas:

• realm: local database engine
• @tcbs/core: architecture contracts
• TCBS layered architecture conventions from real React Native product usage

Support

If this package helps your project, please:

1. Give the repository a star.
2. Share feedback/issues for edge cases.
3. Contribute improvements and examples.

Professional open-source tooling improves fastest with real-world feedback.