@onchaindb/sdk 0.4.0 → 0.4.2

package/src/query-sdk/QueryResult.ts

@@ -0,0 +1,375 @@
+// Query result utilities class matching Rust SDK functionality
+export class QueryResult<T = any> {
+  public data: T[];
+
+  constructor(data: T[]) {
+    this.data = Array.isArray(data) ? data : [data];
+  }
+
+  // ===== BASIC UTILITIES =====
+
+  len(): number {
+    return this.data.length;
+  }
+
+  length(): number {
+    return this.len();
+  }
+
+  isEmpty(): boolean {
+    return this.data.length === 0;
+  }
+
+  first(): T | undefined {
+    return this.data[0];
+  }
+
+  last(): T | undefined {
+    return this.data[this.data.length - 1];
+  }
+
+  get(index: number): T | undefined {
+    return this.data[index];
+  }
+
+  // ===== ITERATION UTILITIES =====
+
+  any(predicate: (item: T) => boolean): boolean {
+    return this.data.some(predicate);
+  }
+
+  all(predicate: (item: T) => boolean): boolean {
+    return this.data.every(predicate);
+  }
+
+  find(predicate: (item: T) => boolean): T | undefined {
+    return this.data.find(predicate);
+  }
+
+  filter(predicate: (item: T) => boolean): T[] {
+    return this.data.filter(predicate);
+  }
+
+  map<U>(transform: (item: T) => U): U[] {
+    return this.data.map(transform);
+  }
+
+  forEach(callback: (item: T, index: number) => void): void {
+    this.data.forEach(callback);
+  }
+
+  reduce<U>(callback: (accumulator: U, item: T, index: number) => U, initialValue: U): U {
+    return this.data.reduce(callback, initialValue);
+  }
+
+  // ===== AGGREGATION UTILITIES =====
+
+  groupBy(field: string): Record<string, T[]> {
+    const groups: Record<string, T[]> = {};
+    
+    this.data.forEach(item => {
+      const key = this.getNestedValue(item, field);
+      const keyString = String(key ?? 'null');
+      
+      if (!groups[keyString]) {
+        groups[keyString] = [];
+      }
+      groups[keyString].push(item);
+    });
+    
+    return groups;
+  }
+
+  // Pluck values from a specific field across all records
+  pluck(field: string): any[] {
+    return this.data.map(item => this.getNestedValue(item, field));
+  }
+
+  pluckStrings(field: string): (string | null)[] {
+    return this.data.map(item => {
+      const value = this.getNestedValue(item, field);
+      return typeof value === 'string' ? value : (value != null ? String(value) : null);
+    });
+  }
+
+  pluckNumbers(field: string): (number | null)[] {
+    return this.data.map(item => {
+      const value = this.getNestedValue(item, field);
+      if (typeof value === 'number' && !isNaN(value)) {
+        return value;
+      }
+      const parsed = Number(value);
+      return !isNaN(parsed) ? parsed : null;
+    });
+  }
+
+  // ===== NUMERIC SUMMARY =====
+
+  summarizeNumeric(field: string): NumericSummary | null {
+    const numbers = this.pluckNumbers(field).filter(n => n !== null) as number[];
+    
+    if (numbers.length === 0) {
+      return null;
+    }
+
+    const sum = numbers.reduce((acc, n) => acc + n, 0);
+    const mean = sum / numbers.length;
+    const min = Math.min(...numbers);
+    const max = Math.max(...numbers);
+
+    // Calculate median
+    const sortedNumbers = [...numbers].sort((a, b) => a - b);
+    const mid = Math.floor(sortedNumbers.length / 2);
+    const median = sortedNumbers.length % 2 !== 0 
+      ? sortedNumbers[mid]
+      : (sortedNumbers[mid - 1] + sortedNumbers[mid]) / 2;
+
+    // Calculate standard deviation
+    const variance = numbers.reduce((acc, n) => acc + Math.pow(n - mean, 2), 0) / numbers.length;
+    const standardDeviation = Math.sqrt(variance);
+
+    return {
+      count: numbers.length,
+      sum,
+      mean,
+      median,
+      min,
+      max,
+      standardDeviation,
+      variance
+    };
+  }
+
+  // ===== SORTING =====
+
+  sortBy(field: string, ascending: boolean = true): T[] {
+    const sorted = [...this.data].sort((a, b) => {
+      const valueA = this.getNestedValue(a, field);
+      const valueB = this.getNestedValue(b, field);
+
+      // Handle null/undefined values
+      if (valueA == null && valueB == null) return 0;
+      if (valueA == null) return ascending ? -1 : 1;
+      if (valueB == null) return ascending ? 1 : -1;
+
+      // Compare values
+      let comparison = 0;
+      if (valueA < valueB) comparison = -1;
+      else if (valueA > valueB) comparison = 1;
+
+      return ascending ? comparison : -comparison;
+    });
+
+    return sorted;
+  }
+
+  // Multiple field sorting
+  sortByMultiple(fields: Array<{field: string, ascending?: boolean}>): T[] {
+    const sorted = [...this.data].sort((a, b) => {
+      for (const {field, ascending = true} of fields) {
+        const valueA = this.getNestedValue(a, field);
+        const valueB = this.getNestedValue(b, field);
+
+        // Handle null/undefined values
+        if (valueA == null && valueB == null) continue;
+        if (valueA == null) return ascending ? -1 : 1;
+        if (valueB == null) return ascending ? 1 : -1;
+
+        // Compare values
+        let comparison = 0;
+        if (valueA < valueB) comparison = -1;
+        else if (valueA > valueB) comparison = 1;
+
+        if (comparison !== 0) {
+          return ascending ? comparison : -comparison;
+        }
+      }
+      return 0;
+    });
+
+    return sorted;
+  }
+
+  // ===== PAGINATION =====
+
+  paginate(page: number, pageSize: number): T[] {
+    const startIndex = (page - 1) * pageSize;
+    const endIndex = startIndex + pageSize;
+    return this.data.slice(startIndex, endIndex);
+  }
+
+  chunk(size: number): T[][] {
+    const chunks: T[][] = [];
+    for (let i = 0; i < this.data.length; i += size) {
+      chunks.push(this.data.slice(i, i + size));
+    }
+    return chunks;
+  }
+
+  // ===== DISTINCT/UNIQUE =====
+
+  distinctBy(field: string): T[] {
+    const seen = new Set();
+    return this.data.filter(item => {
+      const value = this.getNestedValue(item, field);
+      const key = String(value);
+      if (seen.has(key)) {
+        return false;
+      }
+      seen.add(key);
+      return true;
+    });
+  }
+
+  unique(): T[] {
+    return [...new Set(this.data)];
+  }
+
+  // ===== STATISTICAL FUNCTIONS =====
+
+  count(predicate?: (item: T) => boolean): number {
+    if (predicate) {
+      return this.data.filter(predicate).length;
+    }
+    return this.data.length;
+  }
+
+  countBy(field: string): Record<string, number> {
+    const counts: Record<string, number> = {};
+    
+    this.data.forEach(item => {
+      const key = String(this.getNestedValue(item, field) ?? 'null');
+      counts[key] = (counts[key] || 0) + 1;
+    });
+    
+    return counts;
+  }
+
+  // ===== UTILITY METHODS =====
+
+  // Get nested field value using dot notation
+  private getNestedValue(obj: any, path: string): any {
+    return path.split('.').reduce((current, key) => {
+      return current && typeof current === 'object' ? current[key] : undefined;
+    }, obj);
+  }
+
+  // ===== TRANSFORMATION =====
+
+  toArray(): T[] {
+    return [...this.data];
+  }
+
+  toJSON(): string {
+    return JSON.stringify(this.data);
+  }
+
+  // Convert to QueryResult with different type
+  cast<U>(): QueryResult<U> {
+    return new QueryResult(this.data as unknown as U[]);
+  }
+
+  // ===== JOINING (similar to SQL joins) =====
+
+  innerJoin<U>(
+    other: QueryResult<U>, 
+    thisKey: string, 
+    otherKey: string
+  ): Array<T & U> {
+    const results: Array<T & U> = [];
+    
+    this.data.forEach(thisItem => {
+      const thisValue = this.getNestedValue(thisItem, thisKey);
+      other.data.forEach(otherItem => {
+        const otherValue = this.getNestedValue(otherItem, otherKey);
+        if (thisValue === otherValue) {
+          results.push({...thisItem, ...otherItem});
+        }
+      });
+    });
+    
+    return results;
+  }
+
+  leftJoin<U>(
+    other: QueryResult<U>, 
+    thisKey: string, 
+    otherKey: string
+  ): Array<T & Partial<U>> {
+    const results: Array<T & Partial<U>> = [];
+    
+    this.data.forEach(thisItem => {
+      const thisValue = this.getNestedValue(thisItem, thisKey);
+      const matches = other.data.filter(otherItem => 
+        this.getNestedValue(otherItem, otherKey) === thisValue
+      );
+      
+      if (matches.length > 0) {
+        matches.forEach(match => {
+          results.push({...thisItem, ...match});
+        });
+      } else {
+        results.push({...thisItem} as T & Partial<U>);
+      }
+    });
+    
+    return results;
+  }
+
+  // ===== EXPORT/FORMATTING =====
+
+  toCsv(delimiter: string = ','): string {
+    if (this.data.length === 0) return '';
+
+    // Get all unique keys from all objects
+    const allKeys = new Set<string>();
+    this.data.forEach(item => {
+      if (typeof item === 'object' && item !== null) {
+        Object.keys(item).forEach(key => allKeys.add(key));
+      }
+    });
+
+    const headers = Array.from(allKeys);
+    const csvRows = [headers.join(delimiter)];
+
+    this.data.forEach(item => {
+      const row = headers.map(header => {
+        const value = typeof item === 'object' && item !== null ? (item as any)[header] : '';
+        // Escape values that contain the delimiter
+        const stringValue = String(value ?? '');
+        return stringValue.includes(delimiter) ? `"${stringValue}"` : stringValue;
+      });
+      csvRows.push(row.join(delimiter));
+    });
+
+    return csvRows.join('\n');
+  }
+
+  // ===== DEBUGGING =====
+
+  inspect(limit?: number): void {
+    const itemsToShow = limit ? this.data.slice(0, limit) : this.data;
+    console.log('QueryResult:', {
+      count: this.data.length,
+      showing: itemsToShow.length,
+      data: itemsToShow
+    });
+  }
+}
+
+// Numeric summary interface
+export interface NumericSummary {
+  count: number;
+  sum: number;
+  mean: number;
+  median: number;
+  min: number;
+  max: number;
+  standardDeviation: number;
+  variance: number;
+}
+
+// Utility function to create QueryResult
+export function createQueryResult<T>(data: T[]): QueryResult<T> {
+  return new QueryResult(data);
+}