@codai/cbd/dist/universal/UniversalDataModel.d.ts

Codai Better Database - High-Performance Vector Memory System with HPKV-inspired architecture and MCP server

/**
 * CBD Universal Data Model
 * Foundation for multi-paradigm database support
 *
 * Phase 1: Core unified data model supporting all database paradigms
 */
import { z } from 'zod';
/**
 * Universal Record ID that supports all paradigm identification needs
 */
export interface UniversalRecordId {
    id: string;
    sqlTable?: string;
    docCollection?: string;
    graphType?: 'node' | 'edge';
    vectorDimensions?: number;
    timeSeriesMetric?: string;
    keyValueNamespace?: string;
    version: number;
    createdAt: Date;
    updatedAt: Date;
}
/**
 * Data containers for different paradigms
 */
export type DataContainer = RelationalData | DocumentData | GraphData | VectorData | TimeSeriesData | KeyValueData;
/**
 * Relational (SQL) data container
 */
export interface RelationalData {
    type: 'relational';
    schema: string;
    table: string;
    columns: Record<string, any>;
    constraints?: {
        primaryKey?: string[];
        foreignKeys?: Array<{
            column: string;
            references: {
                table: string;
                column: string;
            };
        }>;
        unique?: string[][];
        checks?: Array<{
            name: string;
            expression: string;
        }>;
    };
}
/**
 * Document (NoSQL document) data container
 */
export interface DocumentData {
    type: 'document';
    collection: string;
    document: Record<string, any>;
    schema?: any;
    indexes?: Array<{
        fields: Record<string, 1 | -1>;
        options?: {
            unique?: boolean;
            sparse?: boolean;
            ttl?: number;
        };
    }>;
}
/**
 * Graph data container (nodes and edges)
 */
export interface GraphData {
    type: 'graph';
    nodeType?: string;
    edgeType?: string;
    properties: Record<string, any>;
    labels?: string[];
    sourceNodeId?: string;
    targetNodeId?: string;
    directed?: boolean;
    weight?: number;
}
/**
 * Vector data container
 */
export interface VectorData {
    type: 'vector';
    dimensions: number;
    vector: Float32Array | number[];
    metadata?: Record<string, any>;
    embedding?: {
        model: string;
        sourceText?: string;
        sourceImage?: string;
        sourceAudio?: string;
    };
    indexType?: 'hnsw' | 'ivf' | 'lsh' | 'brute_force';
}
/**
 * Time-series data container
 */
export interface TimeSeriesData {
    type: 'timeseries';
    metric: string;
    timestamp: Date;
    value: number | string | boolean | Record<string, any>;
    tags?: Record<string, string>;
    fields?: Record<string, number | string | boolean>;
    retention?: {
        duration: string;
        aggregation?: 'mean' | 'sum' | 'min' | 'max' | 'count';
    };
}
/**
 * Key-Value data container
 */
export interface KeyValueData {
    type: 'keyvalue';
    namespace?: string;
    key: string;
    value: any;
    ttl?: number;
    dataType?: 'string' | 'number' | 'boolean' | 'json' | 'binary';
    compression?: 'gzip' | 'lz4' | 'zstd';
}
/**
 * Universal Record - the core data structure
 */
export interface UniversalRecord {
    id: UniversalRecordId;
    data: DataContainer;
    indexes: IndexMap;
    metadata: RecordMetadata;
    version: number;
    storageHints?: {
        preferredLayout?: 'row' | 'column' | 'hybrid';
        compressionType?: 'none' | 'snappy' | 'lz4' | 'zstd';
        accessPattern?: 'sequential' | 'random' | 'append_only';
        hotness?: 'hot' | 'warm' | 'cold' | 'archive';
    };
}
/**
 * Index definitions for multi-paradigm support
 */
export interface IndexMap {
    btree?: Array<{
        name: string;
        columns: string[];
        unique?: boolean;
    }>;
    hash?: Array<{
        name: string;
        columns: string[];
    }>;
    fulltext?: Array<{
        name: string;
        columns: string[];
        language?: string;
    }>;
    geospatial?: Array<{
        name: string;
        column: string;
        type: '2d' | '2dsphere' | 'geoHaystack';
    }>;
    vector?: Array<{
        name: string;
        column: string;
        indexType: 'hnsw' | 'ivf' | 'lsh';
        parameters?: Record<string, any>;
    }>;
    graph?: Array<{
        name: string;
        type: 'adjacency' | 'path' | 'centrality';
        direction?: 'in' | 'out' | 'both';
    }>;
    timeseries?: Array<{
        name: string;
        timeColumn: string;
        valueColumns: string[];
        granularity?: 'second' | 'minute' | 'hour' | 'day';
    }>;
}
/**
 * Record metadata
 */
export interface RecordMetadata {
    createdBy: string;
    createdAt: Date;
    updatedBy: string;
    updatedAt: Date;
    accessCount: number;
    lastAccessed: Date;
    source?: string;
    transformations?: Array<{
        type: string;
        timestamp: Date;
        parameters?: Record<string, any>;
    }>;
    classification?: 'public' | 'internal' | 'confidential' | 'restricted';
    encryptionKey?: string;
    auditTrail?: Array<{
        action: string;
        user: string;
        timestamp: Date;
        details?: Record<string, any>;
    }>;
    tenantId?: string;
    permissions?: Array<{
        principal: string;
        actions: string[];
    }>;
    quality?: {
        completeness: number;
        accuracy: number;
        consistency: number;
        freshness: Date;
    };
}
/**
 * Schema validation using Zod for runtime type safety
 */
export declare const UniversalRecordSchema: z.ZodObject<{
    id: z.ZodObject<{
        id: z.ZodString;
        version: z.ZodNumber;
        createdAt: z.ZodDate;
        updatedAt: z.ZodDate;
        sqlTable: z.ZodOptional<z.ZodString>;
        docCollection: z.ZodOptional<z.ZodString>;
        graphType: z.ZodOptional<z.ZodEnum<["node", "edge"]>>;
        vectorDimensions: z.ZodOptional<z.ZodNumber>;
        timeSeriesMetric: z.ZodOptional<z.ZodString>;
        keyValueNamespace: z.ZodOptional<z.ZodString>;
    }, "strip", z.ZodTypeAny, {
        id: string;
        version: number;
        createdAt: Date;
        updatedAt: Date;
        sqlTable?: string | undefined;
        docCollection?: string | undefined;
        graphType?: "node" | "edge" | undefined;
        vectorDimensions?: number | undefined;
        timeSeriesMetric?: string | undefined;
        keyValueNamespace?: string | undefined;
    }, {
        id: string;
        version: number;
        createdAt: Date;
        updatedAt: Date;
        sqlTable?: string | undefined;
        docCollection?: string | undefined;
        graphType?: "node" | "edge" | undefined;
        vectorDimensions?: number | undefined;
        timeSeriesMetric?: string | undefined;
        keyValueNamespace?: string | undefined;
    }>;
    data: z.ZodUnion<[z.ZodObject<{
        type: z.ZodLiteral<"relational">;
        schema: z.ZodString;
        table: z.ZodString;
        columns: z.ZodRecord<z.ZodString, z.ZodAny>;
    }, "strip", z.ZodTypeAny, {
        type: "relational";
        schema: string;
        table: string;
        columns: Record<string, any>;
    }, {
        type: "relational";
        schema: string;
        table: string;
        columns: Record<string, any>;
    }>, z.ZodObject<{
        type: z.ZodLiteral<"document">;
        collection: z.ZodString;
        document: z.ZodRecord<z.ZodString, z.ZodAny>;
    }, "strip", z.ZodTypeAny, {
        document: Record<string, any>;
        type: "document";
        collection: string;
    }, {
        document: Record<string, any>;
        type: "document";
        collection: string;
    }>, z.ZodObject<{
        type: z.ZodLiteral<"graph">;
        properties: z.ZodRecord<z.ZodString, z.ZodAny>;
    }, "strip", z.ZodTypeAny, {
        type: "graph";
        properties: Record<string, any>;
    }, {
        type: "graph";
        properties: Record<string, any>;
    }>, z.ZodObject<{
        type: z.ZodLiteral<"vector">;
        dimensions: z.ZodNumber;
        vector: z.ZodArray<z.ZodNumber, "many">;
    }, "strip", z.ZodTypeAny, {
        vector: number[];
        dimensions: number;
        type: "vector";
    }, {
        vector: number[];
        dimensions: number;
        type: "vector";
    }>, z.ZodObject<{
        type: z.ZodLiteral<"timeseries">;
        metric: z.ZodString;
        timestamp: z.ZodDate;
        value: z.ZodAny;
    }, "strip", z.ZodTypeAny, {
        timestamp: Date;
        type: "timeseries";
        metric: string;
        value?: any;
    }, {
        timestamp: Date;
        type: "timeseries";
        metric: string;
        value?: any;
    }>, z.ZodObject<{
        type: z.ZodLiteral<"keyvalue">;
        key: z.ZodString;
        value: z.ZodAny;
    }, "strip", z.ZodTypeAny, {
        key: string;
        type: "keyvalue";
        value?: any;
    }, {
        key: string;
        type: "keyvalue";
        value?: any;
    }>]>;
    indexes: z.ZodRecord<z.ZodString, z.ZodAny>;
    metadata: z.ZodObject<{
        createdBy: z.ZodString;
        createdAt: z.ZodDate;
        updatedBy: z.ZodString;
        updatedAt: z.ZodDate;
        accessCount: z.ZodNumber;
        lastAccessed: z.ZodDate;
    }, "strip", z.ZodTypeAny, {
        createdAt: Date;
        updatedAt: Date;
        createdBy: string;
        updatedBy: string;
        accessCount: number;
        lastAccessed: Date;
    }, {
        createdAt: Date;
        updatedAt: Date;
        createdBy: string;
        updatedBy: string;
        accessCount: number;
        lastAccessed: Date;
    }>;
    version: z.ZodNumber;
}, "strip", z.ZodTypeAny, {
    id: {
        id: string;
        version: number;
        createdAt: Date;
        updatedAt: Date;
        sqlTable?: string | undefined;
        docCollection?: string | undefined;
        graphType?: "node" | "edge" | undefined;
        vectorDimensions?: number | undefined;
        timeSeriesMetric?: string | undefined;
        keyValueNamespace?: string | undefined;
    };
    metadata: {
        createdAt: Date;
        updatedAt: Date;
        createdBy: string;
        updatedBy: string;
        accessCount: number;
        lastAccessed: Date;
    };
    data: {
        type: "relational";
        schema: string;
        table: string;
        columns: Record<string, any>;
    } | {
        document: Record<string, any>;
        type: "document";
        collection: string;
    } | {
        type: "graph";
        properties: Record<string, any>;
    } | {
        vector: number[];
        dimensions: number;
        type: "vector";
    } | {
        timestamp: Date;
        type: "timeseries";
        metric: string;
        value?: any;
    } | {
        key: string;
        type: "keyvalue";
        value?: any;
    };
    version: number;
    indexes: Record<string, any>;
}, {
    id: {
        id: string;
        version: number;
        createdAt: Date;
        updatedAt: Date;
        sqlTable?: string | undefined;
        docCollection?: string | undefined;
        graphType?: "node" | "edge" | undefined;
        vectorDimensions?: number | undefined;
        timeSeriesMetric?: string | undefined;
        keyValueNamespace?: string | undefined;
    };
    metadata: {
        createdAt: Date;
        updatedAt: Date;
        createdBy: string;
        updatedBy: string;
        accessCount: number;
        lastAccessed: Date;
    };
    data: {
        type: "relational";
        schema: string;
        table: string;
        columns: Record<string, any>;
    } | {
        document: Record<string, any>;
        type: "document";
        collection: string;
    } | {
        type: "graph";
        properties: Record<string, any>;
    } | {
        vector: number[];
        dimensions: number;
        type: "vector";
    } | {
        timestamp: Date;
        type: "timeseries";
        metric: string;
        value?: any;
    } | {
        key: string;
        type: "keyvalue";
        value?: any;
    };
    version: number;
    indexes: Record<string, any>;
}>;
/**
 * Query context for multi-paradigm queries
 */
export interface QueryContext {
    paradigm: 'sql' | 'document' | 'graph' | 'vector' | 'timeseries' | 'keyvalue' | 'hybrid';
    optimizationLevel?: 'fast' | 'balanced' | 'thorough';
    cacheStrategy?: 'none' | 'memory' | 'disk' | 'distributed';
    consistencyLevel?: 'eventual' | 'session' | 'strong';
    user?: string;
    roles?: string[];
    tenantId?: string;
    timeout?: number;
    maxResultSize?: number;
    explain?: boolean;
}
/**
 * Universal query result
 */
export interface QueryResult<T = any> {
    data: T[];
    metadata: {
        executionTime: number;
        recordsScanned: number;
        recordsReturned: number;
        indexesUsed: string[];
        queryPlan?: any;
        cacheHit?: boolean;
    };
    pagination?: {
        hasMore: boolean;
        nextCursor?: string;
        totalCount?: number;
    };
}
/**
 * Factory functions for creating data containers
 */
export declare class DataContainerFactory {
    static createRelational(schema: string, table: string, columns: Record<string, any>): RelationalData;
    static createDocument(collection: string, document: Record<string, any>): DocumentData;
    static createVector(dimensions: number, vector: number[], metadata?: Record<string, any>): VectorData;
    static createTimeSeries(metric: string, value: any, tags?: Record<string, string>): TimeSeriesData;
    static createKeyValue(key: string, value: any, namespace?: string): KeyValueData;
    static createGraphNode(labels: string[], properties: Record<string, any>): GraphData;
    static createGraphEdge(sourceNodeId: string, targetNodeId: string, edgeType: string, properties?: Record<string, any>): GraphData;
}
/**
 * Universal record utilities
 */
export declare class UniversalRecordUtils {
    /**
     * Generate a new universal record ID
     */
    static generateId(paradigm: string, identifier: string): UniversalRecordId;
    /**
     * Validate a universal record
     */
    static validate(record: UniversalRecord): {
        valid: boolean;
        errors: string[];
    };
    /**
     * Create metadata with defaults
     */
    static createMetadata(createdBy: string, tenantId?: string): RecordMetadata;
}
//# sourceMappingURL=UniversalDataModel.d.ts.map