dpth 0.1.0 → 0.3.0

package/dist/dpth.d.ts

@@ -0,0 +1,178 @@
+/**
+ * dpth.io — Unified Database API
+ *
+ * The main entry point. One line to get a persistent, intelligent database
+ * with entity resolution, temporal history, correlation detection, and
+ * optional vector search.
+ *
+ * Usage:
+ *   import { dpth } from 'dpth/dpth';
+ *   const db = await dpth('./myapp.db');
+ *
+ *   // Entity resolution
+ *   const john = db.entity.resolve('person', 'John Smith', 'stripe', 'cus_123');
+ *   db.entity.resolve('person', 'jsmith', 'github', 'jsmith'); // auto-merged
+ *
+ *   // Temporal history
+ *   db.temporal.snapshot('dashboard', { revenue: 50000, users: 200 });
+ *   db.temporal.history('dashboard'); // all snapshots over time
+ *
+ *   // Correlation
+ *   db.correlation.track('mrr', 50000);
+ *   db.correlation.track('deploys', 12);
+ *   db.correlation.find('mrr'); // what correlates with MRR?
+ *
+ *   // Clean up
+ *   await db.close();
+ */
+import type { StorageAdapter, VectorResult } from './storage.js';
+import type { Entity, EntityId, EntityType, SourceId, Metric } from './types.js';
+export interface DpthOptions {
+    /** Storage adapter (default: MemoryAdapter) */
+    adapter?: StorageAdapter;
+    /** Path to SQLite database (convenience — creates SQLiteAdapter) */
+    path?: string;
+}
+export interface ResolveResult {
+    entity: Entity;
+    isNew: boolean;
+    confidence: number;
+}
+export interface SnapshotRecord<T = Record<string, unknown>> {
+    id: string;
+    key: string;
+    timestamp: Date;
+    data: T;
+    source: string;
+}
+export interface DiffResult {
+    added: string[];
+    removed: string[];
+    changed: Array<{
+        key: string;
+        from: unknown;
+        to: unknown;
+    }>;
+}
+export interface CorrelationHit {
+    metricId: string;
+    correlation: number;
+    lagDays: number;
+    direction: 'positive' | 'negative';
+    sampleSize: number;
+}
+export declare class Dpth {
+    private adapter;
+    private _ready;
+    /** Entity resolution and management */
+    entity: EntityAPI;
+    /** Temporal history and snapshots */
+    temporal: TemporalAPI;
+    /** Correlation detection across metrics */
+    correlation: CorrelationAPI;
+    /** Vector search (if adapter supports it) */
+    vector: VectorAPI;
+    constructor(options?: DpthOptions);
+    private init;
+    /** Wait for initialization to complete */
+    ready(): Promise<this>;
+    /** Close the database and flush any pending writes */
+    close(): Promise<void>;
+    /** Get database stats */
+    stats(): Promise<{
+        entities: number;
+        snapshots: number;
+        metrics: number;
+        vectors: number;
+    }>;
+}
+declare class EntityAPI {
+    private adapter;
+    constructor(adapter: StorageAdapter);
+    /** Resolve an entity — find existing match or create new */
+    resolve(type: EntityType, name: string, sourceId: SourceId, externalId: string, options?: {
+        email?: string;
+        aliases?: string[];
+        attributes?: Record<string, unknown>;
+        minConfidence?: number;
+    }): Promise<ResolveResult>;
+    /** Get entity by ID */
+    get(id: EntityId): Promise<Entity | undefined>;
+    /** Find entity by source reference */
+    findBySource(sourceId: SourceId, externalId: string): Promise<Entity | undefined>;
+    /** Get all entities of a type */
+    list(type?: EntityType): Promise<Entity[]>;
+    /** Update an entity attribute (temporal) */
+    setAttribute(entityId: EntityId, key: string, value: unknown, sourceId: SourceId): Promise<Entity | undefined>;
+    /** Merge two entities */
+    merge(keepId: EntityId, mergeId: EntityId): Promise<Entity | undefined>;
+    /** Count entities */
+    count(type?: EntityType): Promise<number>;
+    private findBestMatch;
+    private fuzzyScore;
+}
+declare class TemporalAPI {
+    private adapter;
+    constructor(adapter: StorageAdapter);
+    /** Take a snapshot of any data */
+    snapshot<T = Record<string, unknown>>(key: string, data: T, source?: SourceId): Promise<SnapshotRecord<T>>;
+    /** Get all snapshots for a key (ordered by time) */
+    history<T = Record<string, unknown>>(key: string): Promise<SnapshotRecord<T>[]>;
+    /** Get the latest snapshot for a key */
+    latest<T = Record<string, unknown>>(key: string): Promise<SnapshotRecord<T> | undefined>;
+    /** Get snapshot closest to a specific time */
+    at<T = Record<string, unknown>>(key: string, time: Date): Promise<SnapshotRecord<T> | undefined>;
+    /** Diff two snapshots */
+    diff<T extends Record<string, unknown>>(older: SnapshotRecord<T>, newer: SnapshotRecord<T>): DiffResult;
+}
+declare class CorrelationAPI {
+    private adapter;
+    constructor(adapter: StorageAdapter);
+    /** Track a metric value */
+    track(metricId: string, value: number, options?: {
+        source?: SourceId;
+        entityId?: EntityId;
+        name?: string;
+        unit?: string;
+    }): Promise<void>;
+    /** Find correlations for a metric */
+    find(metricId: string, options?: {
+        minCorrelation?: number;
+        maxLagDays?: number;
+    }): Promise<CorrelationHit[]>;
+    /** Get a metric's history */
+    get(metricId: string): Promise<Metric | undefined>;
+    /** List all tracked metrics */
+    list(): Promise<Metric[]>;
+    private pearson;
+}
+declare class VectorAPI {
+    private adapter;
+    constructor(adapter: StorageAdapter);
+    private get vec();
+    /** Check if vector search is available */
+    get available(): boolean;
+    /** Store a vector */
+    store(collection: string, key: string, vector: number[], metadata?: Record<string, unknown>): Promise<void>;
+    /** Search by vector similarity */
+    search(collection: string, vector: number[], topK?: number, minScore?: number): Promise<VectorResult[]>;
+}
+/**
+ * Create a dpth database instance.
+ *
+ * @param pathOrOptions — SQLite path string, or options object
+ * @returns Initialized Dpth instance (call .ready() if you need to await init)
+ *
+ * @example
+ * // In-memory (default)
+ * const db = dpth();
+ *
+ * // Persistent (SQLite)
+ * const db = await dpth('./myapp.db').ready();
+ *
+ * // Custom adapter
+ * const db = dpth({ adapter: new MemoryVectorAdapter() });
+ */
+export declare function dpth(pathOrOptions?: string | DpthOptions): Dpth;
+export {};
+//# sourceMappingURL=dpth.d.ts.map

package/dist/dpth.d.ts.map

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