@ductape/sdk 0.0.4-v9 → 0.0.4-v90

package/dist/warehouse/types/where.interface.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Unified Where Clause Interface
+ *
+ * A consistent filtering interface that works across databases,
+ * graphs, and vector stores using MongoDB-style operators.
+ */
+/**
+ * Standard comparison operators (work on all data types)
+ */
+export interface IComparisonCondition {
+    /** Equals */
+    $eq?: any;
+    /** Not equals */
+    $ne?: any;
+    /** Greater than */
+    $gt?: any;
+    /** Greater than or equal */
+    $gte?: any;
+    /** Less than */
+    $lt?: any;
+    /** Less than or equal */
+    $lte?: any;
+    /** In array */
+    $in?: any[];
+    /** Not in array */
+    $nin?: any[];
+    /** Between two values (inclusive) */
+    $between?: [any, any];
+    /** Is null */
+    $isNull?: boolean;
+    /** Exists (field is present) */
+    $exists?: boolean;
+}
+/**
+ * String-specific operators
+ */
+export interface IStringCondition extends IComparisonCondition {
+    /** SQL LIKE pattern (case-sensitive) */
+    $like?: string;
+    /** SQL ILIKE pattern (case-insensitive) */
+    $ilike?: string;
+    /** Starts with prefix */
+    $startsWith?: string;
+    /** Ends with suffix */
+    $endsWith?: string;
+    /** Contains substring */
+    $contains?: string;
+    /** Regular expression match */
+    $regex?: string | {
+        pattern: string;
+        flags?: string;
+    };
+}
+/**
+ * Array-specific operators
+ */
+export interface IArrayCondition extends IComparisonCondition {
+    /** Array contains value */
+    $contains?: any;
+    /** Array is contained by */
+    $containedBy?: any[];
+    /** Arrays overlap */
+    $overlaps?: any[];
+    /** Array has length */
+    $size?: number;
+    /** All elements match condition */
+    $all?: any[];
+    /** At least one element matches */
+    $elemMatch?: IUnifiedWhereClause;
+}
+/**
+ * JSON/Object-specific operators
+ */
+export interface IJsonCondition extends IComparisonCondition {
+    /** JSON path exists */
+    $hasKey?: string;
+    /** JSON contains */
+    $jsonContains?: Record<string, any>;
+    /** Contained by JSON */
+    $jsonContainedBy?: Record<string, any>;
+}
+/**
+ * Vector similarity operator (for semantic search)
+ */
+export interface IVectorSimilarityCondition {
+    $similar?: {
+        /** Vector to compare against */
+        vector: number[];
+        /** Minimum similarity threshold (0-1 for cosine) */
+        threshold?: number;
+        /** Maximum number of similar items */
+        topK?: number;
+        /** Distance metric */
+        metric?: 'cosine' | 'euclidean' | 'dot_product';
+    };
+}
+/**
+ * Graph connectivity operator
+ */
+export interface IGraphConnectivityCondition {
+    $connected?: {
+        /**
+         * Target node specification
+         * Can be node ID or "Label:property=value"
+         */
+        to: string;
+        /** Relationship type to traverse */
+        via?: string;
+        /** Maximum traversal depth */
+        maxDepth?: number;
+        /** Direction of traversal */
+        direction?: 'outgoing' | 'incoming' | 'both';
+    };
+    /** Node has specific label */
+    $hasLabel?: string | string[];
+    /** Relationship exists */
+    $hasRelationship?: {
+        type: string;
+        direction?: 'outgoing' | 'incoming' | 'both';
+        properties?: IUnifiedWhereClause;
+    };
+}
+/**
+ * Full-text search operator
+ */
+export interface IFullTextCondition {
+    $text?: {
+        /** Search query */
+        search: string;
+        /** Language for stemming */
+        language?: string;
+        /** Case sensitive */
+        caseSensitive?: boolean;
+        /** Diacritic sensitive */
+        diacriticSensitive?: boolean;
+    };
+    $match?: {
+        /** Match query */
+        query: string;
+        /** Fields to search */
+        fields?: string[];
+        /** Fuzziness level */
+        fuzziness?: number | 'auto';
+    };
+}
+/**
+ * All possible field conditions
+ */
+export type IFieldCondition = IComparisonCondition & IStringCondition & IArrayCondition & IJsonCondition & IVectorSimilarityCondition & IGraphConnectivityCondition & IFullTextCondition;
+/**
+ * Logical operators for combining conditions
+ */
+export interface ILogicalOperators {
+    /** All conditions must match */
+    $and?: IUnifiedWhereClause[];
+    /** At least one condition must match */
+    $or?: IUnifiedWhereClause[];
+    /** Condition must not match */
+    $not?: IUnifiedWhereClause;
+    /** None of the conditions must match */
+    $nor?: IUnifiedWhereClause[];
+}
+/**
+ * Unified where clause that works across all data source types
+ *
+ * @example
+ * // Simple equality
+ * { "u.status": { $eq: "active" } }
+ *
+ * @example
+ * // Complex with logical operators
+ * {
+ *   $and: [
+ *     { "u.age": { $gte: 18 } },
+ *     { $or: [
+ *       { "u.status": { $eq: "active" } },
+ *       { "u.role": { $eq: "admin" } }
+ *     ]}
+ *   ]
+ * }
+ *
+ * @example
+ * // Vector similarity
+ * { "embedding": { $similar: { vector: [...], threshold: 0.8 } } }
+ *
+ * @example
+ * // Graph connectivity
+ * { "node": { $connected: { to: "Category:AI", via: "BELONGS_TO" } } }
+ */
+export type IUnifiedWhereClause = ILogicalOperators & {
+    [fieldPath: string]: IFieldCondition | any;
+};
+/**
+ * Check if a where clause is empty
+ */
+export declare function isEmptyWhereClause(where?: IUnifiedWhereClause): boolean;
+/**
+ * Check if a condition uses vector operators
+ */
+export declare function hasVectorOperators(where?: IUnifiedWhereClause): boolean;
+/**
+ * Check if a condition uses graph operators
+ */
+export declare function hasGraphOperators(where?: IUnifiedWhereClause): boolean;
+/**
+ * Extract field paths from a where clause
+ */
+export declare function extractFieldPaths(where?: IUnifiedWhereClause): string[];

package/dist/warehouse/types/where.interface.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Unified Where Clause Interface
+ *
+ * A consistent filtering interface that works across databases,
+ * graphs, and vector stores using MongoDB-style operators.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEmptyWhereClause = isEmptyWhereClause;
+exports.hasVectorOperators = hasVectorOperators;
+exports.hasGraphOperators = hasGraphOperators;
+exports.extractFieldPaths = extractFieldPaths;
+// ==================== WHERE CLAUSE UTILITIES ====================
+/**
+ * Check if a where clause is empty
+ */
+function isEmptyWhereClause(where) {
+    if (!where)
+        return true;
+    return Object.keys(where).length === 0;
+}
+/**
+ * Check if a condition uses vector operators
+ */
+function hasVectorOperators(where) {
+    if (!where)
+        return false;
+    for (const [, value] of Object.entries(where)) {
+        if (value && typeof value === 'object') {
+            if ('$similar' in value)
+                return true;
+        }
+    }
+    // Check nested logical operators
+    if (where.$and) {
+        return where.$and.some(hasVectorOperators);
+    }
+    if (where.$or) {
+        return where.$or.some(hasVectorOperators);
+    }
+    return false;
+}
+/**
+ * Check if a condition uses graph operators
+ */
+function hasGraphOperators(where) {
+    if (!where)
+        return false;
+    for (const [, value] of Object.entries(where)) {
+        if (value && typeof value === 'object') {
+            if ('$connected' in value || '$hasLabel' in value || '$hasRelationship' in value) {
+                return true;
+            }
+        }
+    }
+    // Check nested logical operators
+    if (where.$and) {
+        return where.$and.some(hasGraphOperators);
+    }
+    if (where.$or) {
+        return where.$or.some(hasGraphOperators);
+    }
+    return false;
+}
+/**
+ * Extract field paths from a where clause
+ */
+function extractFieldPaths(where) {
+    if (!where)
+        return [];
+    const paths = [];
+    for (const [key, value] of Object.entries(where)) {
+        // Skip logical operators
+        if (key.startsWith('$')) {
+            if (key === '$and' || key === '$or' || key === '$nor') {
+                const nested = value;
+                nested.forEach(w => paths.push(...extractFieldPaths(w)));
+            }
+            else if (key === '$not') {
+                paths.push(...extractFieldPaths(value));
+            }
+        }
+        else {
+            paths.push(key);
+        }
+    }
+    return [...new Set(paths)];
+}
+//# sourceMappingURL=where.interface.js.map

package/dist/warehouse/types/where.interface.js.map

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

package/dist/warehouse/warehouse.service.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Warehouse Service
+ *
+ * Unified data warehouse interface for querying and writing data across
+ * databases, graphs, and vector stores using a single JSON interface.
+ *
+ * Features:
+ * - Cross-database joins (hash, nested loop, sort-merge)
+ * - Semantic joins (vector similarity)
+ * - Graph traversal joins
+ * - Unified where clauses
+ * - Distributed transactions (Saga pattern)
+ * - Query parsing and validation
+ */
+import { DatabaseService } from '../database/databases.service';
+import { GraphService } from '../graph/graphs.service';
+import { VectorDatabaseService } from '../vector/vector-database.service';
+import { IWarehouseQuery, IWarehouseResult, IDataSource, ISagaTransaction, ISagaResult, DataSourceType } from './types';
+import { IRegistryConfig } from './registry';
+/**
+ * Warehouse service configuration
+ */
+export interface IWarehouseConfig {
+    /** Registry configuration */
+    registry?: IRegistryConfig;
+    /** Default query timeout (ms) */
+    defaultTimeout?: number;
+    /** Enable query caching */
+    enableCache?: boolean;
+    /** Cache TTL (seconds) */
+    cacheTtl?: number;
+    /** Maximum join memory (bytes) */
+    maxJoinMemory?: number;
+    /** Enable parallel execution */
+    parallel?: boolean;
+    /** Embedding function for semantic joins */
+    embedFn?: (text: string) => Promise<number[]>;
+}
+/**
+ * Context for warehouse operations
+ */
+export interface IWarehouseContext {
+    /** Default environment */
+    env: string;
+    /** Default product */
+    product: string;
+}
+/**
+ * Warehouse Service
+ *
+ * Main entry point for the unified data warehouse interface.
+ * Orchestrates queries across databases, graphs, and vector stores.
+ */
+export declare class WarehouseService {
+    private readonly databaseService;
+    private readonly graphService;
+    private readonly vectorService;
+    private readonly context;
+    private readonly config;
+    private readonly registry;
+    private readonly parser;
+    private readonly singleSourceExecutor;
+    private readonly joinExecutor;
+    private readonly semanticJoinExecutor;
+    private readonly sagaOrchestrator;
+    constructor(databaseService: DatabaseService, graphService: GraphService, vectorService: VectorDatabaseService, context: IWarehouseContext, config?: IWarehouseConfig);
+    /**
+     * Register a database data source
+     */
+    registerDatabase(tag: string, env?: string, product?: string): Promise<void>;
+    /**
+     * Register a graph data source
+     */
+    registerGraph(tag: string, env?: string, product?: string): Promise<void>;
+    /**
+     * Register a vector data source
+     */
+    registerVector(tag: string, env?: string, product?: string): Promise<void>;
+    /**
+     * Get registered data sources
+     */
+    getDataSources(type?: DataSourceType): import("./registry").IRegisteredDataSource[];
+    /**
+     * Execute a warehouse query
+     *
+     * @example
+     * // Simple database query
+     * const result = await warehouse.query({
+     *   operation: 'select',
+     *   from: { type: 'database', tag: 'users-pg', entity: 'users', alias: 'u' },
+     *   fields: ['u.id', 'u.name', 'u.email'],
+     *   where: { 'u.status': { $eq: 'active' } },
+     *   limit: 100
+     * });
+     *
+     * @example
+     * // Cross-database join
+     * const result = await warehouse.query({
+     *   operation: 'select',
+     *   from: { type: 'database', tag: 'users-pg', entity: 'users', alias: 'u' },
+     *   fields: ['u.name', 'o.total'],
+     *   join: [{
+     *     type: 'left',
+     *     source: { type: 'database', tag: 'orders-mongo', entity: 'orders', alias: 'o' },
+     *     on: { left: 'u.id', right: 'o.userId' }
+     *   }],
+     *   where: { 'u.status': { $eq: 'active' } }
+     * });
+     *
+     * @example
+     * // Semantic join (vector similarity)
+     * const result = await warehouse.query({
+     *   operation: 'select',
+     *   from: { type: 'database', tag: 'products-pg', entity: 'products', alias: 'p' },
+     *   join: [{
+     *     type: 'semantic',
+     *     source: { type: 'vector', tag: 'embeddings-pinecone', entity: 'products', alias: 's' },
+     *     semantic: { embedField: 'p.description', similarityThreshold: 0.8, topK: 5 }
+     *   }]
+     * });
+     */
+    query<T = Record<string, any>>(query: IWarehouseQuery): Promise<IWarehouseResult<T>>;
+    /**
+     * Execute a single query (for saga orchestrator)
+     */
+    private executeSingleQuery;
+    /**
+     * Select from a single source
+     */
+    select<T = Record<string, any>>(source: IDataSource, options?: {
+        fields?: string[];
+        where?: Record<string, any>;
+        orderBy?: {
+            field: string;
+            order: 'ASC' | 'DESC';
+        }[];
+        limit?: number;
+        offset?: number;
+    }): Promise<T[]>;
+    /**
+     * Insert into a source
+     */
+    insert<T = Record<string, any>>(source: IDataSource, data: Record<string, any> | Record<string, any>[], options?: {
+        returning?: boolean;
+    }): Promise<IWarehouseResult<T>>;
+    /**
+     * Update in a source
+     */
+    update<T = Record<string, any>>(source: IDataSource, data: Record<string, any>, where: Record<string, any>, options?: {
+        returning?: boolean;
+    }): Promise<IWarehouseResult<T>>;
+    /**
+     * Delete from a source
+     */
+    delete<T = Record<string, any>>(source: IDataSource, where: Record<string, any>, options?: {
+        returning?: boolean;
+    }): Promise<IWarehouseResult<T>>;
+    /**
+     * Upsert into a source
+     */
+    upsert<T = Record<string, any>>(source: IDataSource, data: Record<string, any>, options?: {
+        returning?: boolean;
+    }): Promise<IWarehouseResult<T>>;
+    /**
+     * Execute multiple operations in a saga transaction
+     */
+    transaction(operations: Omit<IWarehouseQuery, 'transaction'>[], options?: Partial<ISagaTransaction>): Promise<ISagaResult>;
+    /**
+     * Execute a single-source query
+     */
+    private executeSingleSource;
+    /**
+     * Execute a query with cross-database joins
+     */
+    private executeWithJoins;
+    /**
+     * Execute a single join operation
+     */
+    private executeJoin;
+    /**
+     * Execute a graph traversal join
+     */
+    private executeGraphJoin;
+    /**
+     * Execute query with transaction
+     */
+    private executeWithTransaction;
+    /**
+     * Merge two rows
+     */
+    private mergeRows;
+    /**
+     * Project result to requested fields
+     */
+    private projectFields;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}