@tallyui/database 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+import { RxDatabase, RxCollection, RxStorage } from 'rxdb';
+import { TallyConnector, ReplicationAdapter, SyncContext } from '@tallyui/core';
+import { RxReplicationState } from 'rxdb/plugins/replication';
+
+/**
+ * The shape of a Tally database — keyed by collection name.
+ */
+type TallyDatabase = RxDatabase<{
+    [key: string]: RxCollection;
+}>;
+interface CreateDatabaseOptions {
+    /** The connector whose schemas define the collections */
+    connector: TallyConnector;
+    /** Database name (defaults to `tally_${connector.id}`) */
+    name?: string;
+    /** RxDB storage adapter (defaults to in-memory for dev/demo) */
+    storage?: any;
+}
+/**
+ * Create an RxDB database from a connector's schemas.
+ *
+ * This is the main entry point — give it a connector and it builds
+ * the database with the right collections and schemas.
+ *
+ * ```ts
+ * import { woocommerceConnector } from '@tallyui/connector-woocommerce';
+ * import { createTallyDatabase } from '@tallyui/database';
+ *
+ * const db = await createTallyDatabase({ connector: woocommerceConnector });
+ * const products = await db.products.find().exec();
+ * ```
+ */
+declare function createTallyDatabase(options: CreateDatabaseOptions): Promise<TallyDatabase>;
+
+/**
+ * Returns the appropriate RxDB storage adapter for the current platform.
+ *
+ * - Web browser: Dexie (IndexedDB)
+ * - React Native: throws with guidance to provide SQLite storage explicitly
+ * - Node/SSR/test: In-memory
+ *
+ * Override by passing a storage directly to createTallyDatabase().
+ */
+declare function getStorage(): RxStorage<any, any>;
+
+interface StartReplicationOptions<RxDocType, CheckpointType = any> {
+    collection: RxCollection<RxDocType>;
+    adapter: ReplicationAdapter<RxDocType, CheckpointType>;
+    context: SyncContext;
+    /** Keep syncing after initial pull (default: true) */
+    live?: boolean;
+    /** Retry interval in ms on error (default: 5000) */
+    retryTime?: number;
+    /** Start immediately (default: true) */
+    autoStart?: boolean;
+}
+/**
+ * Start RxDB replication for a single collection using a ReplicationAdapter.
+ *
+ * Returns the RxReplicationState which exposes observables for monitoring
+ * and methods like cancel(), awaitInSync(), reSync().
+ */
+declare function startReplication<RxDocType, CheckpointType = any>({ collection, adapter, context, live, retryTime, autoStart, }: StartReplicationOptions<RxDocType, CheckpointType>): RxReplicationState<RxDocType, CheckpointType>;
+
+export { type CreateDatabaseOptions, type StartReplicationOptions, type TallyDatabase, createTallyDatabase, getStorage, startReplication };

package/dist/index.js

@@ -0,0 +1,80 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/create-db.ts
+import { createRxDatabase, addRxPlugin } from "rxdb";
+import { RxDBDevModePlugin } from "rxdb/plugins/dev-mode";
+import { getRxStorageMemory } from "rxdb/plugins/storage-memory";
+if (process.env.NODE_ENV !== "production") {
+  addRxPlugin(RxDBDevModePlugin);
+}
+async function createTallyDatabase(options) {
+  const {
+    connector,
+    name = `tally_${connector.id}`,
+    storage = getRxStorageMemory()
+  } = options;
+  const db = await createRxDatabase({
+    name,
+    storage,
+    multiInstance: false,
+    ignoreDuplicate: true
+  });
+  const collectionConfigs = {};
+  for (const [collectionName, schema] of Object.entries(connector.schemas)) {
+    collectionConfigs[collectionName] = { schema };
+  }
+  await db.addCollections(collectionConfigs);
+  return db;
+}
+
+// src/storage.ts
+import { getRxStorageMemory as getRxStorageMemory2 } from "rxdb/plugins/storage-memory";
+function getStorage() {
+  if (typeof window === "undefined") {
+    return getRxStorageMemory2();
+  }
+  if (typeof navigator !== "undefined" && navigator.product === "ReactNative") {
+    throw new Error(
+      'React Native detected. Pass a storage adapter explicitly:\n  import { getRxStorageSQLite } from "@tallyui/storage-sqlite";\n  createTallyDatabase({ connector, storage: getRxStorageSQLite({ database }) })'
+    );
+  }
+  const { getRxStorageDexie } = __require("rxdb/plugins/storage-dexie");
+  return getRxStorageDexie();
+}
+
+// src/replication.ts
+import { replicateRxCollection } from "rxdb/plugins/replication";
+function startReplication({
+  collection,
+  adapter,
+  context,
+  live = true,
+  retryTime = 5e3,
+  autoStart = true
+}) {
+  return replicateRxCollection({
+    collection,
+    replicationIdentifier: `${context.connectorId}-${collection.name}`,
+    pull: {
+      handler: (checkpoint, batchSize) => adapter.pull.handler(checkpoint, batchSize, context),
+      stream$: adapter.pull.stream$
+    },
+    push: adapter.push ? {
+      handler: (rows) => adapter.push.handler(rows, context),
+      batchSize: adapter.push.batchSize
+    } : void 0,
+    live,
+    retryTime,
+    autoStart
+  });
+}
+export {
+  createTallyDatabase,
+  getStorage,
+  startReplication
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@tallyui/database",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "RxDB database factory for Tally UI — accepts pluggable connector schemas",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "source": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "source": "./src/index.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "rxdb": "16.21.1",
+    "rxjs": "7.8.2"
+  },
+  "peerDependencies": {
+    "@tallyui/core": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "echo \"no tests yet\""
+  }
+}

package/src/create-db.ts

@@ -0,0 +1,65 @@
+import { createRxDatabase, addRxPlugin, type RxDatabase, type RxCollection } from 'rxdb';
+import { RxDBDevModePlugin } from 'rxdb/plugins/dev-mode';
+import { getRxStorageMemory } from 'rxdb/plugins/storage-memory';
+
+import type { TallyConnector } from '@tallyui/core';
+
+// Enable dev mode in non-production
+if (process.env.NODE_ENV !== 'production') {
+  addRxPlugin(RxDBDevModePlugin);
+}
+
+/**
+ * The shape of a Tally database — keyed by collection name.
+ */
+export type TallyDatabase = RxDatabase<{
+  [key: string]: RxCollection;
+}>;
+
+export interface CreateDatabaseOptions {
+  /** The connector whose schemas define the collections */
+  connector: TallyConnector;
+  /** Database name (defaults to `tally_${connector.id}`) */
+  name?: string;
+  /** RxDB storage adapter (defaults to in-memory for dev/demo) */
+  storage?: any;
+}
+
+/**
+ * Create an RxDB database from a connector's schemas.
+ *
+ * This is the main entry point — give it a connector and it builds
+ * the database with the right collections and schemas.
+ *
+ * ```ts
+ * import { woocommerceConnector } from '@tallyui/connector-woocommerce';
+ * import { createTallyDatabase } from '@tallyui/database';
+ *
+ * const db = await createTallyDatabase({ connector: woocommerceConnector });
+ * const products = await db.products.find().exec();
+ * ```
+ */
+export async function createTallyDatabase(options: CreateDatabaseOptions): Promise<TallyDatabase> {
+  const {
+    connector,
+    name = `tally_${connector.id}`,
+    storage = getRxStorageMemory(),
+  } = options;
+
+  const db = await createRxDatabase({
+    name,
+    storage,
+    multiInstance: false,
+    ignoreDuplicate: true,
+  });
+
+  // Build collection configs from connector schemas
+  const collectionConfigs: Record<string, { schema: any }> = {};
+  for (const [collectionName, schema] of Object.entries(connector.schemas)) {
+    collectionConfigs[collectionName] = { schema };
+  }
+
+  await db.addCollections(collectionConfigs);
+
+  return db as TallyDatabase;
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export { createTallyDatabase } from './create-db';
+export type { TallyDatabase, CreateDatabaseOptions } from './create-db';
+
+export { getStorage } from './storage';
+
+export { startReplication } from './replication';
+export type { StartReplicationOptions } from './replication';

package/src/replication.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { createRxDatabase, addRxPlugin } from 'rxdb';
+import { RxDBDevModePlugin } from 'rxdb/plugins/dev-mode';
+import { getRxStorageMemory } from 'rxdb/plugins/storage-memory';
+import { wrappedValidateAjvStorage } from 'rxdb/plugins/validate-ajv';
+
+import { startReplication } from './replication';
+import type { ReplicationAdapter, SyncContext } from '@tallyui/core';
+
+addRxPlugin(RxDBDevModePlugin);
+
+const storage = wrappedValidateAjvStorage({ storage: getRxStorageMemory() });
+
+const testSchema = {
+  version: 0,
+  primaryKey: 'id',
+  type: 'object' as const,
+  properties: {
+    id: { type: 'string', maxLength: 100 },
+    name: { type: 'string' },
+  },
+  required: ['id', 'name'],
+};
+
+const context: SyncContext = {
+  connectorId: 'test',
+  baseUrl: 'https://example.com',
+  headers: {},
+};
+
+describe('startReplication', () => {
+  let db: any;
+
+  beforeEach(async () => {
+    db = await createRxDatabase({
+      name: `test_${Date.now()}`,
+      storage,
+      multiInstance: false,
+      ignoreDuplicate: true,
+    });
+    await db.addCollections({ products: { schema: testSchema } });
+  });
+
+  afterEach(async () => {
+    await db?.close();
+  });
+
+  it('starts replication and pulls documents', async () => {
+    const adapter: ReplicationAdapter<any, any> = {
+      pull: {
+        handler: vi.fn().mockResolvedValueOnce({
+          documents: [
+            { id: '1', name: 'Widget', _deleted: false },
+          ],
+          checkpoint: { id: '1' },
+        }).mockResolvedValue({
+          documents: [],
+          checkpoint: { id: '1' },
+        }),
+      },
+    };
+
+    const state = startReplication({
+      collection: db.products,
+      adapter,
+      context,
+    });
+
+    await state.awaitInSync();
+
+    const docs = await db.products.find().exec();
+    expect(docs).toHaveLength(1);
+    expect(docs[0].name).toBe('Widget');
+
+    await state.cancel();
+  });
+
+  it('returns RxReplicationState with observables', async () => {
+    const adapter: ReplicationAdapter<any, any> = {
+      pull: {
+        handler: vi.fn().mockResolvedValue({ documents: [], checkpoint: {} }),
+      },
+    };
+
+    const state = startReplication({
+      collection: db.products,
+      adapter,
+      context,
+    });
+
+    expect(state.error$).toBeDefined();
+    expect(state.active$).toBeDefined();
+    expect(state.received$).toBeDefined();
+
+    await state.cancel();
+  });
+});

package/src/replication.ts

@@ -0,0 +1,50 @@
+import { replicateRxCollection, type RxReplicationState } from 'rxdb/plugins/replication';
+import type { RxCollection } from 'rxdb';
+
+import type { ReplicationAdapter, SyncContext } from '@tallyui/core';
+
+export interface StartReplicationOptions<RxDocType, CheckpointType = any> {
+  collection: RxCollection<RxDocType>;
+  adapter: ReplicationAdapter<RxDocType, CheckpointType>;
+  context: SyncContext;
+  /** Keep syncing after initial pull (default: true) */
+  live?: boolean;
+  /** Retry interval in ms on error (default: 5000) */
+  retryTime?: number;
+  /** Start immediately (default: true) */
+  autoStart?: boolean;
+}
+
+/**
+ * Start RxDB replication for a single collection using a ReplicationAdapter.
+ *
+ * Returns the RxReplicationState which exposes observables for monitoring
+ * and methods like cancel(), awaitInSync(), reSync().
+ */
+export function startReplication<RxDocType, CheckpointType = any>({
+  collection,
+  adapter,
+  context,
+  live = true,
+  retryTime = 5000,
+  autoStart = true,
+}: StartReplicationOptions<RxDocType, CheckpointType>): RxReplicationState<RxDocType, CheckpointType> {
+  return replicateRxCollection({
+    collection,
+    replicationIdentifier: `${context.connectorId}-${collection.name}`,
+    pull: {
+      handler: (checkpoint, batchSize) =>
+        adapter.pull.handler(checkpoint as CheckpointType | undefined, batchSize, context),
+      stream$: adapter.pull.stream$,
+    },
+    push: adapter.push
+      ? {
+          handler: (rows) => adapter.push!.handler(rows, context),
+          batchSize: adapter.push.batchSize,
+        }
+      : undefined,
+    live,
+    retryTime,
+    autoStart,
+  });
+}

package/src/storage.test.ts

@@ -0,0 +1,19 @@
+// @vitest-environment node
+import { describe, it, expect } from 'vitest';
+
+import { getStorage } from './storage';
+
+describe('getStorage', () => {
+  it('returns a storage object with a name property', () => {
+    const storage = getStorage();
+    expect(storage).toBeDefined();
+    expect(storage.name).toBeDefined();
+    expect(typeof storage.createStorageInstance).toBe('function');
+  });
+
+  it('returns memory storage in node/test environment', () => {
+    const storage = getStorage();
+    // In Node.js (test env), we expect memory storage
+    expect(storage.name).toBe('memory');
+  });
+});

package/src/storage.ts

@@ -0,0 +1,33 @@
+import type { RxStorage } from 'rxdb';
+import { getRxStorageMemory } from 'rxdb/plugins/storage-memory';
+
+/**
+ * Returns the appropriate RxDB storage adapter for the current platform.
+ *
+ * - Web browser: Dexie (IndexedDB)
+ * - React Native: throws with guidance to provide SQLite storage explicitly
+ * - Node/SSR/test: In-memory
+ *
+ * Override by passing a storage directly to createTallyDatabase().
+ */
+export function getStorage(): RxStorage<any, any> {
+  // Node.js / SSR / test — no persistent storage needed
+  if (typeof window === 'undefined') {
+    return getRxStorageMemory();
+  }
+
+  // React Native — no IndexedDB available.
+  // Users must provide SQLite storage explicitly via createTallyDatabase({ storage }).
+  if (typeof navigator !== 'undefined' && navigator.product === 'ReactNative') {
+    throw new Error(
+      'React Native detected. Pass a storage adapter explicitly:\n' +
+      '  import { getRxStorageSQLite } from "@tallyui/storage-sqlite";\n' +
+      '  createTallyDatabase({ connector, storage: getRxStorageSQLite({ database }) })'
+    );
+  }
+
+  // Web browser — use Dexie (IndexedDB)
+  // Dynamic import avoided here; Dexie is bundled with rxdb.
+  const { getRxStorageDexie } = require('rxdb/plugins/storage-dexie');
+  return getRxStorageDexie();
+}