@prabhask5/stellar-engine 1.1.18 → 1.2.1

package/dist/crdt/store.js

@@ -0,0 +1,158 @@
+/**
+ * @fileoverview CRDT IndexedDB Persistence Layer
+ *
+ * Provides CRUD operations for the two CRDT-specific IndexedDB tables:
+ *   - `crdtDocuments` — Full Yjs document state snapshots
+ *   - `crdtPendingUpdates` — Incremental Yjs update deltas for crash recovery
+ *
+ * These tables are conditionally created by {@link ../database.ts#buildDexie}
+ * only when `crdt` config is provided to `initEngine()`.
+ *
+ * This module also exposes offline management query functions:
+ *   - {@link isOfflineEnabled} — check if a document is stored for offline
+ *   - {@link getOfflineDocuments} — list all offline-enabled documents
+ *   - {@link getOfflineDocumentCount} — count for limit enforcement
+ *
+ * All functions access Dexie via the engine-managed instance from
+ * {@link ../database.ts#getDb}. Binary Yjs state is stored directly as
+ * `Uint8Array` — Dexie/IndexedDB handles binary data natively.
+ *
+ * @see {@link ./types.ts} for record shapes (CRDTDocumentRecord, CRDTPendingUpdate)
+ * @see {@link ./provider.ts} for the orchestrator that calls these functions
+ * @see {@link ../database.ts} for conditional CRDT table creation
+ */
+import { getDb } from '../database';
+import { debugLog } from '../debug';
+// =============================================================================
+//  Document State CRUD
+// =============================================================================
+/**
+ * Load a CRDT document record from IndexedDB.
+ *
+ * @param documentId - The unique document identifier.
+ * @returns The document record, or `undefined` if not found.
+ */
+export async function loadDocumentState(documentId) {
+    const db = getDb();
+    return db.table('crdtDocuments').get(documentId);
+}
+/**
+ * Save a full CRDT document state snapshot to IndexedDB.
+ *
+ * Uses Dexie's `put()` for upsert semantics — creates a new record if the
+ * document doesn't exist, or overwrites the existing one.
+ *
+ * @param record - The full document record to persist.
+ */
+export async function saveDocumentState(record) {
+    const db = getDb();
+    await db.table('crdtDocuments').put(record);
+    debugLog(`[CRDT] Document ${record.documentId}: local save (${record.stateSize} bytes to IndexedDB)`);
+}
+/**
+ * Delete a CRDT document record from IndexedDB.
+ *
+ * Also clears all associated pending updates for the document.
+ *
+ * @param documentId - The document to delete.
+ */
+export async function deleteDocumentState(documentId) {
+    const db = getDb();
+    await db.table('crdtDocuments').delete(documentId);
+    await clearPendingUpdates(documentId);
+}
+/**
+ * Load a CRDT document record by page ID.
+ *
+ * Pages may have at most one CRDT document. Returns the first match.
+ *
+ * @param pageId - The page/entity ID to look up.
+ * @returns The document record, or `undefined` if not found.
+ */
+export async function loadDocumentByPageId(pageId) {
+    const db = getDb();
+    return db.table('crdtDocuments').where('pageId').equals(pageId).first();
+}
+// =============================================================================
+//  Pending Updates (Crash Recovery)
+// =============================================================================
+/**
+ * Append an incremental Yjs update to the pending updates table.
+ *
+ * Called on every `doc.on('update')` event for crash safety. If the browser
+ * crashes between full-state saves (every 5s), these deltas can be replayed
+ * to recover the document.
+ *
+ * @param documentId - The document this update belongs to.
+ * @param update - The incremental Yjs update delta.
+ */
+export async function appendPendingUpdate(documentId, update) {
+    const db = getDb();
+    const record = {
+        documentId,
+        update,
+        timestamp: new Date().toISOString()
+    };
+    await db.table('crdtPendingUpdates').add(record);
+}
+/**
+ * Load all pending updates for a specific document, ordered by ID (insertion order).
+ *
+ * Used during document opening to replay any updates that weren't captured
+ * in the last full-state save.
+ *
+ * @param documentId - The document to load updates for.
+ * @returns Array of pending update records, oldest first.
+ */
+export async function loadPendingUpdates(documentId) {
+    const db = getDb();
+    return db.table('crdtPendingUpdates').where('documentId').equals(documentId).sortBy('id');
+}
+/**
+ * Clear all pending updates for a document.
+ *
+ * Called after a successful full-state save to IndexedDB or Supabase persist,
+ * since the updates have been captured in the full state snapshot.
+ *
+ * @param documentId - The document to clear updates for.
+ * @returns The number of updates cleared.
+ */
+export async function clearPendingUpdates(documentId) {
+    const db = getDb();
+    return db.table('crdtPendingUpdates').where('documentId').equals(documentId).delete();
+}
+// =============================================================================
+//  Offline Management Queries
+// =============================================================================
+/**
+ * Check whether a specific document is stored for offline access.
+ *
+ * @param documentId - The document to check.
+ * @returns `true` if the document has `offlineEnabled: 1` in IndexedDB.
+ */
+export async function isOfflineEnabled(documentId) {
+    const record = await loadDocumentState(documentId);
+    return record?.offlineEnabled === 1;
+}
+/**
+ * Get all documents that are stored for offline access.
+ *
+ * @returns Array of document records with `offlineEnabled: 1`.
+ */
+export async function getOfflineDocuments() {
+    const db = getDb();
+    return db.table('crdtDocuments').where('offlineEnabled').equals(1).toArray();
+}
+/**
+ * Count the number of documents currently stored for offline access.
+ *
+ * Used by {@link ./offline.ts#enableOffline} to enforce the
+ * `maxOfflineDocuments` limit.
+ *
+ * @returns The number of offline-enabled documents.
+ */
+export async function getOfflineDocumentCount() {
+    const db = getDb();
+    return db.table('crdtDocuments').where('offlineEnabled').equals(1).count();
+}
+//# sourceMappingURL=store.js.map

package/dist/crdt/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/crdt/store.ts"],"names":[],"mappings":"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"}

package/dist/crdt/types.d.ts

@@ -0,0 +1,281 @@
+/**
+ * @fileoverview CRDT Subsystem Type Definitions
+ *
+ * Defines all TypeScript interfaces and types used by the CRDT collaborative
+ * editing subsystem. This includes:
+ *   - {@link CRDTConfig} — configuration passed via `initEngine({ crdt: ... })`
+ *   - {@link CRDTDocumentRecord} — IndexedDB record shape for persisted CRDT state
+ *   - {@link CRDTPendingUpdate} — crash-safe incremental update records
+ *   - {@link UserPresenceState} — per-user cursor/presence state for awareness
+ *   - {@link OpenDocumentOptions} — options bag for `openDocument()`
+ *   - {@link BroadcastMessage} — union of all Broadcast channel message types
+ *
+ * Architecture note:
+ *   The CRDT subsystem is an optional layer on top of the existing sync engine.
+ *   It uses Yjs for conflict-free document merging, Supabase Broadcast for
+ *   real-time update distribution, Supabase Presence for cursor/awareness,
+ *   and IndexedDB (via Dexie) for local persistence. Consumers never import
+ *   yjs directly — all Yjs types are re-exported from the engine.
+ *
+ * @see {@link ./config.ts} for configuration singleton management
+ * @see {@link ./provider.ts} for the per-document lifecycle orchestrator
+ * @see {@link ./channel.ts} for Broadcast message handling
+ * @see {@link ./awareness.ts} for Supabase Presence ↔ Yjs Awareness bridge
+ */
+/**
+ * Configuration for the CRDT collaborative editing subsystem.
+ *
+ * Passed as the `crdt` field of {@link SyncEngineConfig} in `initEngine()`.
+ * All fields are optional with sensible defaults. When this config is provided,
+ * the engine creates additional IndexedDB tables for CRDT document storage and
+ * enables the `@prabhask5/stellar-engine/crdt` API surface.
+ *
+ * @example
+ * initEngine({
+ *   prefix: 'myapp',
+ *   tables: [...],
+ *   database: { name: 'myapp-db', versions: [...] },
+ *   crdt: {
+ *     persistIntervalMs: 60000,   // Persist to Supabase every 60s
+ *     maxOfflineDocuments: 100,    // Allow up to 100 docs offline
+ *   },
+ * });
+ */
+export interface CRDTConfig {
+    /**
+     * Supabase table name for CRDT document storage.
+     * @default 'crdt_documents'
+     */
+    supabaseTable?: string;
+    /**
+     * Columns to SELECT from Supabase (egress optimization).
+     * @default 'id,page_id,state,state_vector,state_size,device_id,updated_at,created_at'
+     */
+    columns?: string;
+    /**
+     * How often to persist dirty documents to Supabase (ms).
+     * Lower values reduce data loss risk on crash but increase Supabase writes.
+     * @default 30000 (30 seconds)
+     */
+    persistIntervalMs?: number;
+    /**
+     * Broadcast debounce window (ms). Updates within this window are merged
+     * via `Y.mergeUpdates()` into a single Broadcast payload.
+     * @default 100
+     */
+    broadcastDebounceMs?: number;
+    /**
+     * How long to debounce local IndexedDB full-state saves (ms).
+     * Writes full Yjs state to IndexedDB on this interval to ensure recovery
+     * from crashes without storing every single keystroke.
+     * @default 5000 (5 seconds)
+     */
+    localSaveDebounceMs?: number;
+    /**
+     * Cursor/presence update debounce (ms). Limits the rate at which
+     * cursor position changes are broadcast to other users.
+     * @default 50
+     */
+    cursorDebounceMs?: number;
+    /**
+     * Maximum number of documents stored locally for offline access.
+     * When the limit is reached, `enableOffline()` will reject new documents.
+     * @default 50
+     */
+    maxOfflineDocuments?: number;
+    /**
+     * Maximum Broadcast payload size in bytes before chunking.
+     * Supabase Broadcast has a ~1MB hard limit; we chunk well below that.
+     * @default 250000 (250KB)
+     */
+    maxBroadcastPayloadBytes?: number;
+    /**
+     * Timeout (ms) waiting for peer sync-step-2 responses on reconnect.
+     * If no peers respond within this window, falls back to Supabase fetch.
+     * @default 3000
+     */
+    syncPeerTimeoutMs?: number;
+    /**
+     * Maximum reconnection attempts for the Broadcast channel.
+     * After this many failures, the channel enters a permanent error state
+     * and must be manually reconnected.
+     * @default 5
+     */
+    maxReconnectAttempts?: number;
+    /**
+     * Base delay (ms) for exponential backoff on channel reconnect.
+     * Actual delay: `baseDelay * 2^(attemptNumber - 1)`.
+     * @default 1000
+     */
+    reconnectBaseDelayMs?: number;
+}
+/**
+ * Fully resolved CRDT configuration with all defaults applied.
+ *
+ * Created by {@link config.ts#_initCRDT} from the user-provided
+ * {@link CRDTConfig}. All fields are required (no `undefined` values).
+ *
+ * @internal
+ */
+export interface ResolvedCRDTConfig {
+    supabaseTable: string;
+    columns: string;
+    persistIntervalMs: number;
+    broadcastDebounceMs: number;
+    localSaveDebounceMs: number;
+    cursorDebounceMs: number;
+    maxOfflineDocuments: number;
+    maxBroadcastPayloadBytes: number;
+    syncPeerTimeoutMs: number;
+    maxReconnectAttempts: number;
+    reconnectBaseDelayMs: number;
+}
+/**
+ * Shape of a record in the `crdtDocuments` IndexedDB table.
+ *
+ * Stores the full Yjs document state as a binary `Uint8Array`, along with
+ * metadata for sync, offline management, and diagnostics.
+ *
+ * The `offlineEnabled` field uses `0 | 1` instead of `boolean` because
+ * Dexie/IndexedDB cannot index boolean fields.
+ */
+export interface CRDTDocumentRecord {
+    /** Unique document identifier (primary key). */
+    documentId: string;
+    /** The page/entity this document belongs to. Indexed for lookups. */
+    pageId: string;
+    /** Full Yjs document state (`Y.encodeStateAsUpdate(doc)`). */
+    state: Uint8Array;
+    /** Yjs state vector for delta sync (`Y.encodeStateVector(doc)`). */
+    stateVector: Uint8Array;
+    /**
+     * Whether this document is stored locally for offline access.
+     * Uses `0 | 1` because IndexedDB cannot index booleans.
+     */
+    offlineEnabled: 0 | 1;
+    /** ISO 8601 timestamp of the last local modification. */
+    localUpdatedAt: string;
+    /** ISO 8601 timestamp of the last successful Supabase write, or `null` if never persisted. */
+    lastPersistedAt: string | null;
+    /** Byte size of the `state` field, for diagnostics and compaction decisions. */
+    stateSize: number;
+}
+/**
+ * Shape of a record in the `crdtPendingUpdates` IndexedDB table.
+ *
+ * Stores incremental Yjs update deltas for crash safety. These are written
+ * on every `doc.on('update')` event so that if the browser crashes between
+ * full-state saves (every 5s), the pending deltas can be replayed to recover
+ * the document to its last known state.
+ *
+ * Cleared after a successful full-state save to IndexedDB or Supabase persist.
+ */
+export interface CRDTPendingUpdate {
+    /** Auto-increment primary key (assigned by IndexedDB). */
+    id?: number;
+    /** Which document this update belongs to. Indexed for efficient batch queries. */
+    documentId: string;
+    /** Incremental Yjs update delta (`Uint8Array` from `doc.on('update')`). */
+    update: Uint8Array;
+    /** ISO 8601 timestamp of when the update was received. */
+    timestamp: string;
+}
+/**
+ * Per-user presence state broadcast via Supabase Presence and bridged to
+ * Yjs Awareness. This is what other users see when collaborating on a document.
+ *
+ * The `cursor` and `selection` fields are intentionally typed as `unknown`
+ * because their shape depends on the editor implementation (Tiptap, Prosemirror,
+ * CodeMirror, etc.). The CRDT engine transports them opaquely.
+ */
+export interface UserPresenceState {
+    /** Supabase user UUID. */
+    userId: string;
+    /** Display name (e.g., first name or email). */
+    name: string;
+    /** Avatar URL, if available. */
+    avatarUrl?: string;
+    /**
+     * Deterministic color assigned from userId hash.
+     * Used for cursor color, selection highlight, avatar ring, etc.
+     */
+    color: string;
+    /** Editor-specific cursor position (opaque to the engine). */
+    cursor?: unknown;
+    /** Editor-specific selection range (opaque to the engine). */
+    selection?: unknown;
+    /** Device identifier for multi-tab dedup. */
+    deviceId: string;
+    /** ISO 8601 timestamp of the user's last activity in this document. */
+    lastActiveAt: string;
+}
+/**
+ * Options for {@link provider.ts#openDocument}.
+ */
+export interface OpenDocumentOptions {
+    /**
+     * If `true`, the document will be persisted to IndexedDB for offline access.
+     * When `false` or omitted, the document exists only in memory and is lost
+     * when the provider is destroyed.
+     * @default false
+     */
+    offlineEnabled?: boolean;
+    /**
+     * Initial user presence state to announce when joining the document.
+     * If omitted, no presence is announced until `updateCursor()` is called.
+     */
+    initialPresence?: {
+        name: string;
+        avatarUrl?: string;
+    };
+}
+/**
+ * Connection state of a CRDT document's Broadcast channel.
+ */
+export type CRDTConnectionState = 'disconnected' | 'connecting' | 'connected';
+/**
+ * A CRDT document update distributed via Supabase Broadcast.
+ *
+ * Contains the merged Yjs update (possibly the result of debouncing multiple
+ * rapid edits) encoded as a base64 string for JSON transport.
+ */
+export interface BroadcastUpdateMessage {
+    type: 'update';
+    data: string;
+    deviceId: string;
+}
+/**
+ * Sync step 1: sent on channel join to request missing updates from peers.
+ * Contains the local state vector so peers can compute the delta.
+ */
+export interface BroadcastSyncStep1Message {
+    type: 'sync-step-1';
+    stateVector: string;
+    deviceId: string;
+}
+/**
+ * Sync step 2: response to a sync-step-1 request.
+ * Contains the computed delta update for the requester.
+ */
+export interface BroadcastSyncStep2Message {
+    type: 'sync-step-2';
+    update: string;
+    deviceId: string;
+}
+/**
+ * A chunk of a large Broadcast payload that exceeds the max payload size.
+ * The receiver reassembles chunks by matching `chunkId` and ordering by `index`.
+ */
+export interface BroadcastChunkMessage {
+    type: 'chunk';
+    chunkId: string;
+    index: number;
+    total: number;
+    data: string;
+    deviceId: string;
+}
+/**
+ * Union of all Broadcast message types sent over the CRDT channel.
+ */
+export type BroadcastMessage = BroadcastUpdateMessage | BroadcastSyncStep1Message | BroadcastSyncStep2Message | BroadcastChunkMessage;
+//# sourceMappingURL=types.d.ts.map

package/dist/crdt/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/crdt/types.ts"],"names":[],"mappings":"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"}

package/dist/crdt/types.js

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview CRDT Subsystem Type Definitions
+ *
+ * Defines all TypeScript interfaces and types used by the CRDT collaborative
+ * editing subsystem. This includes:
+ *   - {@link CRDTConfig} — configuration passed via `initEngine({ crdt: ... })`
+ *   - {@link CRDTDocumentRecord} — IndexedDB record shape for persisted CRDT state
+ *   - {@link CRDTPendingUpdate} — crash-safe incremental update records
+ *   - {@link UserPresenceState} — per-user cursor/presence state for awareness
+ *   - {@link OpenDocumentOptions} — options bag for `openDocument()`
+ *   - {@link BroadcastMessage} — union of all Broadcast channel message types
+ *
+ * Architecture note:
+ *   The CRDT subsystem is an optional layer on top of the existing sync engine.
+ *   It uses Yjs for conflict-free document merging, Supabase Broadcast for
+ *   real-time update distribution, Supabase Presence for cursor/awareness,
+ *   and IndexedDB (via Dexie) for local persistence. Consumers never import
+ *   yjs directly — all Yjs types are re-exported from the engine.
+ *
+ * @see {@link ./config.ts} for configuration singleton management
+ * @see {@link ./provider.ts} for the per-document lifecycle orchestrator
+ * @see {@link ./channel.ts} for Broadcast message handling
+ * @see {@link ./awareness.ts} for Supabase Presence ↔ Yjs Awareness bridge
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/crdt/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/crdt/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG"}

package/dist/database.d.ts

@@ -44,6 +44,21 @@ export interface DatabaseConfig {
     /** Ordered list of version declarations (each adds or modifies tables). */
     versions: DatabaseVersionConfig[];
 }
+/**
+ * Dexie indexes automatically appended to every app table when using the
+ * schema-driven API (`initEngine({ schema: {...} })`).
+ *
+ * These correspond to the system columns that every synced table has:
+ * - `id`         — UUID primary key
+ * - `user_id`    — ownership filter for RLS
+ * - `created_at` — creation timestamp
+ * - `updated_at` — last modification timestamp (sync cursor)
+ * - `deleted`    — soft-delete flag
+ * - `_version`   — optimistic concurrency version counter
+ *
+ * @see {@link config.ts#generateDatabaseFromSchema} for usage
+ */
+export declare const SYSTEM_INDEXES = "id, user_id, created_at, updated_at, deleted, _version";
 /**
  * Create a Dexie database with system tables auto-merged into every version.
  *
@@ -62,7 +77,7 @@ export interface DatabaseConfig {
  * @param config - Database name and version declarations.
  * @returns The opened Dexie instance, ready for use.
  */
-export declare function createDatabase(config: DatabaseConfig): Promise<Dexie>;
+export declare function createDatabase(config: DatabaseConfig, crdtEnabled?: boolean): Promise<Dexie>;
 /**
  * Get the engine-managed Dexie instance.
  *
@@ -80,6 +95,56 @@ export declare function getDb(): Dexie;
  * @internal
  */
 export declare function _setManagedDb(db: Dexie): void;
+/**
+ * Result of schema version computation.
+ *
+ * Contains the resolved version number plus the previous stores schema
+ * (if any) so that the caller can declare both versions and give Dexie
+ * a proper upgrade path.
+ */
+export interface SchemaVersionResult {
+    /** The resolved Dexie version number (positive integer, starts at 1). */
+    version: number;
+    /**
+     * The previous version's store schema, or `null` if this is the first
+     * run or no change was detected. When non-null, the caller should declare
+     * **both** `previousStores` at `version - 1` and the current stores at
+     * `version` so Dexie can perform a non-destructive upgrade.
+     */
+    previousStores: Record<string, string> | null;
+    /** The previous version number, or `null` if no upgrade is needed. */
+    previousVersion: number | null;
+}
+/**
+ * Compute a stable Dexie version number from a merged store schema.
+ *
+ * Uses a localStorage-backed hash comparison to detect schema changes:
+ *   1. Compute a deterministic hash of the stringified stores object.
+ *   2. Compare to the previously stored hash in localStorage.
+ *   3. If changed → increment the stored version, persist both hash and
+ *      previous stores schema, and return the upgrade info.
+ *   4. If unchanged → return the stored version.
+ *   5. If first run → return version 1.
+ *
+ * When a schema change is detected, the previous stores schema is returned
+ * so that the caller can declare both versions. This gives Dexie a proper
+ * upgrade path (version N → version N+1) instead of requiring a full
+ * database rebuild.
+ *
+ * @param prefix - Application prefix for namespacing localStorage keys.
+ * @param mergedStores - The complete Dexie store schema (app + system tables).
+ * @returns Version info including previous stores for upgrade path.
+ *
+ * @example
+ * const result = computeSchemaVersion('stellar', {
+ *   goals: 'id, user_id, goal_list_id, order',
+ * });
+ * // First run:  { version: 1, previousStores: null, previousVersion: null }
+ * // On change:  { version: 2, previousStores: { goals: '...' }, previousVersion: 1 }
+ *
+ * @see {@link config.ts#generateDatabaseFromSchema} for the caller
+ */
+export declare function computeSchemaVersion(prefix: string, mergedStores: Record<string, string>): SchemaVersionResult;
 /**
  * Delete the IndexedDB database entirely and clear associated state.
  *

package/dist/database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAM1B;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,sEAAsE;IACtE,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,OAAO,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,QAAQ,EAAE,qBAAqB,EAAE,CAAC;CACnC;AAmCD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,KAAK,CAAC,CAsD3E;AA+BD;;;;;GAKG;AACH,wBAAgB,KAAK,IAAI,KAAK,CAK7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,KAAK,GAAG,IAAI,CAE7C;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyB5D"}
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAM1B;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,sEAAsE;IACtE,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,OAAO,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,QAAQ,EAAE,qBAAqB,EAAE,CAAC;CACnC;AAMD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,2DAA2D,CAAC;AAoDvF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,WAAW,UAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,CAsDhG;AAoCD;;;;;GAKG;AACH,wBAAgB,KAAK,IAAI,KAAK,CAK7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,KAAK,GAAG,IAAI,CAE7C;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC9C,sEAAsE;IACtE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,mBAAmB,CA+CrB;AAyBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyB5D"}