@onchaindb/sdk 0.4.0 → 0.4.2

package/src/query-sdk/README.md

@@ -0,0 +1,866 @@
+# OnChainDB Query SDK
+
+The Query SDK provides a powerful fluent API for building queries with server-side JOINs, complex logical operators, field conditions, and result processing utilities.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [QueryBuilder](#querybuilder)
+- [Aggregations](#aggregations)
+- [Server-Side JOINs](#server-side-joins)
+- [Logical Operators](#logical-operators)
+- [Field Operators](#field-operators)
+- [Selection](#selection)
+- [QueryResult Utilities](#queryresult-utilities)
+- [Nested Field Queries](#nested-field-queries)
+- [OnChainDB Static Class](#onchaindb-static-class)
+- [HTTP Adapters](#http-adapters)
+- [API Reference](#api-reference)
+
+## Quick Start
+
+```typescript
+import { createClient } from '@onchaindb/sdk';
+
+const db = createClient({
+  endpoint: 'http://localhost:9092',
+  appId: 'my_app'
+});
+
+// Simple query
+const result = await db.queryBuilder()
+  .collection('users')
+  .whereField('status').equals('active')
+  .selectFields(['id', 'name', 'email'])
+  .limit(10)
+  .execute();
+
+console.log(result.records);
+```
+
+## QueryBuilder
+
+The QueryBuilder provides a fluent interface for constructing queries.
+
+### Basic Methods
+
+```typescript
+const query = db.queryBuilder()
+  .collection('users')           // Set target collection
+  .whereField('status').equals('active')  // Add filter condition
+  .selectFields(['id', 'name'])  // Select specific fields
+  .selectAll()                   // Or select all fields
+  .limit(50)                     // Limit results
+  .offset(100)                   // Skip results (pagination)
+  .orderBy('created_at')         // Sort results
+  .includeHistory(true)          // Include historical versions
+  .execute();                    // Execute the query
+```
+
+### executeUnique()
+
+Returns the latest record by metadata timestamp (`updatedAt` or `createdAt`). Useful for finding a single record when multiple versions may exist.
+
+```typescript
+// Find the latest user record by email
+const user = await db.queryBuilder()
+  .collection('users')
+  .whereField('email').equals('alice@example.com')
+  .executeUnique<User>();
+
+// Returns: User | null (latest version by timestamp)
+```
+
+### WhereField Operators
+
+All operators available on `whereField()`:
+
+```typescript
+// Comparison
+.equals(value)
+.notEquals(value)
+.greaterThan(value)
+.greaterThanOrEqual(value)
+.lessThan(value)
+.lessThanOrEqual(value)
+.between(min, max)
+
+// String
+.contains(value)
+.startsWith(value)
+.endsWith(value)
+.regExpMatches(pattern)
+.includesCaseInsensitive(value)
+.startsWithCaseInsensitive(value)
+.endsWithCaseInsensitive(value)
+
+// Array
+.in(values)
+.notIn(values)
+
+// Existence
+.exists()
+.notExists()
+.isNull()
+.isNotNull()
+.isTrue()
+.isFalse()
+
+// IP Address
+.isLocalIp()
+.isExternalIp()
+.inCountry(countryCode)
+.cidr(cidrRange)
+
+// Special
+.b64(value)
+.inDataset(dataset)
+```
+
+### Debugging
+
+```typescript
+// Get raw query object for debugging
+const rawQuery = db.queryBuilder()
+  .collection('tweets')
+  .whereField('author').equals('alice')
+  .selectAll()
+  .buildRawQuery();
+
+console.log(JSON.stringify(rawQuery, null, 2));
+
+// Clone a query builder
+const baseQuery = db.queryBuilder().collection('users').selectAll();
+const activeUsers = baseQuery.clone().whereField('active').isTrue();
+const inactiveUsers = baseQuery.clone().whereField('active').isFalse();
+```
+
+## Aggregations
+
+QueryBuilder provides built-in aggregation methods for counting, summing, averaging, and grouping data.
+
+### Basic Aggregations
+
+```typescript
+// Count records
+const activeUsers = await db.queryBuilder()
+  .collection('users')
+  .whereField('active').equals(true)
+  .count();
+// Returns: number
+
+// Sum a numeric field
+const totalRevenue = await db.queryBuilder()
+  .collection('orders')
+  .whereField('status').equals('completed')
+  .sumBy('amount');
+// Returns: number
+
+// Calculate average
+const avgPrice = await db.queryBuilder()
+  .collection('products')
+  .whereField('category').equals('electronics')
+  .avgBy('price');
+// Returns: number
+
+// Find maximum value
+const highestPrice = await db.queryBuilder()
+  .collection('products')
+  .maxBy('price');
+// Returns: T | null
+
+// Find minimum value
+const lowestPrice = await db.queryBuilder()
+  .collection('products')
+  .minBy('price');
+// Returns: T | null
+
+// Get distinct values
+const categories = await db.queryBuilder()
+  .collection('products')
+  .distinctBy('category');
+// Returns: string[]
+
+// Count distinct values
+const uniqueCategories = await db.queryBuilder()
+  .collection('products')
+  .countDistinct('category');
+// Returns: number
+```
+
+### Grouped Aggregations
+
+Use `groupBy()` to perform aggregations on groups of records:
+
+```typescript
+// Count users by country
+const usersByCountry = await db.queryBuilder()
+  .collection('users')
+  .groupBy('country')
+  .count();
+// Returns: { "USA": 150, "UK": 75, "Germany": 50 }
+
+// Sum order amounts by category
+const salesByCategory = await db.queryBuilder()
+  .collection('orders')
+  .whereField('status').equals('completed')
+  .groupBy('category')
+  .sumBy('amount');
+// Returns: { "electronics": 50000, "clothing": 25000 }
+
+// Average rating by product
+const avgRatingByProduct = await db.queryBuilder()
+  .collection('reviews')
+  .groupBy('productId')
+  .avgBy('rating');
+// Returns: { "prod_1": 4.5, "prod_2": 3.8 }
+
+// Max/Min by group
+const maxPriceByCategory = await db.queryBuilder()
+  .collection('products')
+  .groupBy('category')
+  .maxBy('price');
+// Returns: { "electronics": 999, "books": 49 }
+```
+
+### Nested Field Grouping
+
+GroupBy supports nested field paths:
+
+```typescript
+// Group by nested field
+const ordersByRegion = await db.queryBuilder()
+  .collection('orders')
+  .groupBy('customer.address.region')
+  .sumBy('total');
+// Returns: { "West": 10000, "East": 8500 }
+```
+
+## Server-Side JOINs
+
+Server-side JOINs execute on the backend in a single request. Use `$data.fieldname` to reference parent record fields.
+
+### joinOne (One-to-One)
+
+Returns a single object or null. Use when you expect at most one related record.
+
+```typescript
+const result = await db.queryBuilder()
+  .collection('tweets')
+  .joinOne('author_info', 'users')
+    .onField('address').equals('$data.author')
+    .selectFields(['display_name', 'avatar_url', 'verified'])
+    .build()
+  .selectAll()
+  .execute();
+
+// Result: { id, content, author, author_info: { display_name, ... } | null }
+```
+
+### joinMany (One-to-Many)
+
+Returns an array of related records. Use when you expect multiple related records.
+
+```typescript
+const result = await db.queryBuilder()
+  .collection('users')
+  .joinMany('tweets', 'tweets')
+    .onField('author').equals('$data.address')
+    .selectFields(['id', 'content', 'created_at'])
+    .build()
+  .selectAll()
+  .execute();
+
+// Result: { address, name, tweets: [{ id, content, ... }, ...] }
+```
+
+### joinWith (Default Behavior)
+
+Returns an array (same as joinMany but without explicit many flag).
+
+```typescript
+const result = await db.queryBuilder()
+  .collection('posts')
+  .joinWith('comments', 'comments')
+    .onField('post_id').equals('$data.id')
+    .selectAll()
+    .build()
+  .selectAll()
+  .execute();
+```
+
+### Multiple JOINs
+
+```typescript
+const result = await db.queryBuilder()
+  .collection('tweets')
+  .whereField('reply_to_id').isNull()
+  // Author profile (one-to-one)
+  .joinOne('author_info', 'users')
+    .onField('address').equals('$data.author')
+    .selectFields(['display_name', 'avatar_url', 'verified'])
+    .build()
+  // All likes (one-to-many)
+  .joinMany('likes', 'likes')
+    .onField('tweet_id').equals('$data.id')
+    .selectFields(['user', 'created_at'])
+    .build()
+  // All replies (one-to-many)
+  .joinMany('replies', 'tweets')
+    .onField('reply_to_id').equals('$data.id')
+    .selectFields(['id', 'author', 'content'])
+    .build()
+  .selectAll()
+  .limit(20)
+  .execute();
+```
+
+### Nested JOINs
+
+Chain JOINs before calling `.build()` to create nested relationships:
+
+```typescript
+const result = await db.queryBuilder()
+  .collection('tweets')
+  .whereField('id').equals(tweetId)
+  // Get replies with their authors
+  .joinMany('replies', 'tweets')
+    .onField('reply_to_id').equals('$data.id')
+    .selectAll()
+    // Nested: get author for each reply
+    .joinOne('author_info', 'users')
+      .onField('address').equals('$data.author')
+      .selectFields(['display_name', 'avatar_url'])
+      .build()
+    .build()
+  .selectAll()
+  .execute();
+```
+
+### Self-Referential JOINs
+
+```typescript
+// Get tweets with quoted tweet info
+const result = await db.queryBuilder()
+  .collection('tweets')
+  .whereField('quote_tweet_id').isNotNull()
+  .joinOne('quote_tweet', 'tweets')
+    .onField('id').equals('$data.quote_tweet_id')
+    .selectFields(['id', 'content', 'author', 'created_at'])
+    .joinOne('author_info', 'users')
+      .onField('address').equals('$data.author')
+      .selectFields(['display_name', 'avatar_url'])
+      .build()
+    .build()
+  .selectAll()
+  .execute();
+```
+
+### JoinBuilder Operators
+
+Available on `onField()`:
+
+```typescript
+.equals(value)
+.in(values)
+.greaterThan(value)
+.lessThan(value)
+.isNull()
+.isNotNull()
+```
+
+## Logical Operators
+
+Build complex conditions with AND, OR, and NOT:
+
+```typescript
+import { LogicalOperator } from '@onchaindb/sdk';
+
+const result = await db.queryBuilder()
+  .collection('posts')
+  .find(builder =>
+    LogicalOperator.And([
+      LogicalOperator.Condition(builder.field('published').equals(true)),
+      LogicalOperator.Or([
+        LogicalOperator.Condition(builder.field('category').equals('tech')),
+        LogicalOperator.Condition(builder.field('views').greaterThan(1000))
+      ]),
+      LogicalOperator.Not([
+        LogicalOperator.Condition(builder.field('archived').equals(true))
+      ])
+    ])
+  )
+  .selectAll()
+  .execute();
+```
+
+### ConditionBuilder Methods
+
+```typescript
+import { ConditionBuilder, LogicalOperator } from '@onchaindb/sdk';
+
+const builder = new ConditionBuilder();
+
+// Create field conditions
+builder.field('name').equals('John')
+builder.field('age').greaterThan(18)
+
+// Group conditions
+builder.andGroup(() => [...conditions])
+builder.orGroup(() => [...conditions])
+builder.notGroup(() => [...conditions])
+
+// Nested field conditions (ORM-like)
+builder.nested('user', nested =>
+  nested.andGroup(() => [
+    LogicalOperator.Condition(nested.field('profile').field('name').equals('John')),
+    LogicalOperator.Condition(nested.field('settings').field('theme').equals('dark'))
+  ])
+)
+```
+
+## Field Operators
+
+### FieldConditionBuilder
+
+All available operators:
+
+```typescript
+import { FieldConditionBuilder } from '@onchaindb/sdk';
+
+const field = new FieldConditionBuilder('fieldName');
+
+// Base operators
+field.equals(value)        // is
+field.notEquals(value)     // isNot
+field.in(values)           // in
+field.notIn(values)        // notIn
+field.isNull()             // isNull: true
+field.isNotNull()          // isNull: false
+field.exists()             // exists: true
+field.notExists()          // exists: false
+
+// String operators
+field.startsWith(value)
+field.endsWith(value)
+field.contains(value)      // includes
+field.regExpMatches(pattern)
+field.includesCaseInsensitive(value)
+field.startsWithCaseInsensitive(value)
+field.endsWithCaseInsensitive(value)
+
+// Number operators
+field.greaterThan(value)
+field.lessThan(value)
+field.greaterThanOrEqual(value)
+field.lessThanOrEqual(value)
+field.between(min, max)    // betweenOp: { from, to }
+
+// IP operators
+field.isLocalIp()
+field.isExternalIp()
+field.inCountry(countryCode)
+field.cidr(cidrRange)
+
+// Misc operators
+field.b64(value)           // Base64 comparison
+field.inDataset(dataset)   // Dataset membership
+
+// Convenience
+field.isTrue()             // equals(true)
+field.isFalse()            // equals(false)
+```
+
+## Selection
+
+### SelectionBuilder
+
+```typescript
+import { SelectionBuilder } from '@onchaindb/sdk';
+
+// Select specific fields
+const selection = new SelectionBuilder()
+  .field('id')
+  .field('name')
+  .field('email')
+  .build();
+
+// Select multiple fields at once
+new SelectionBuilder()
+  .fields(['id', 'name', 'email', 'created_at'])
+  .build();
+
+// Nested field selection
+new SelectionBuilder()
+  .field('id')
+  .nested('profile', nested => nested.field('bio').field('avatar'))
+  .build();
+
+// Exclude fields
+new SelectionBuilder()
+  .excludeFields(['password', 'secret_key'])
+  .build();
+
+// Select all fields
+SelectionBuilder.all();  // Returns {}
+```
+
+### Using with QueryBuilder
+
+```typescript
+// Method 1: selectFields()
+db.queryBuilder()
+  .collection('users')
+  .selectFields(['id', 'name', 'email'])
+  .execute();
+
+// Method 2: selectAll()
+db.queryBuilder()
+  .collection('users')
+  .selectAll()
+  .execute();
+
+// Method 3: select() with builder
+db.queryBuilder()
+  .collection('users')
+  .select(s => s.field('id').field('name').nested('profile', n => n.field('bio')))
+  .execute();
+```
+
+## QueryResult Utilities
+
+Process query results with built-in utilities:
+
+```typescript
+import { createQueryResult, QueryResult } from '@onchaindb/sdk';
+
+const result = createQueryResult(response.records);
+
+// Basic utilities
+result.len()               // Count of records
+result.isEmpty()           // Check if empty
+result.first()             // First record or undefined
+result.last()              // Last record or undefined
+result.get(5)              // Get record at index
+
+// Iteration
+result.any(r => r.active)           // Any match predicate?
+result.all(r => r.verified)         // All match predicate?
+result.find(r => r.id === '123')    // Find first matching
+result.filter(r => r.status === 'active')
+result.map(r => r.name)
+result.forEach((r, i) => console.log(i, r))
+result.reduce((acc, r) => acc + r.amount, 0)
+
+// Aggregation
+result.groupBy('department')        // { 'sales': [...], 'engineering': [...] }
+result.pluck('name')                // ['Alice', 'Bob', ...]
+result.pluckStrings('name')         // Type-safe string pluck
+result.pluckNumbers('age')          // Type-safe number pluck
+result.countBy('status')            // { 'active': 10, 'inactive': 3 }
+
+// Numeric summary
+const stats = result.summarizeNumeric('salary');
+// { count, sum, mean, median, min, max, standardDeviation, variance }
+
+// Sorting
+result.sortBy('name')                           // Ascending
+result.sortBy('created_at', false)              // Descending
+result.sortByMultiple([
+  { field: 'department', ascending: true },
+  { field: 'salary', ascending: false }
+])
+
+// Pagination
+result.paginate(2, 20)              // Page 2, 20 items per page
+result.chunk(10)                    // Split into chunks of 10
+
+// Distinct
+result.distinctBy('email')          // Unique by field
+result.unique()                     // Unique records
+
+// Joining (client-side)
+const departments = createQueryResult(deptData);
+result.innerJoin(departments, 'dept_id', 'id')
+result.leftJoin(departments, 'dept_id', 'id')
+
+// Export
+result.toCsv()                      // CSV string
+result.toCsv(';')                   // Custom delimiter
+result.toJSON()                     // JSON string
+result.toArray()                    // Plain array
+
+// Debugging
+result.inspect()                    // Log to console
+result.inspect(5)                   // Log first 5 records
+```
+
+## Nested Field Queries
+
+Query nested objects with dot notation or ORM-like builders:
+
+### Dot Notation
+
+```typescript
+// Query nested fields with dot notation
+const result = await db.queryBuilder()
+  .collection('users')
+  .whereField('profile.settings.theme').equals('dark')
+  .selectAll()
+  .execute();
+```
+
+### ORM-like Nested Builder
+
+```typescript
+import { NestedConditionBuilder, LogicalOperator } from '@onchaindb/sdk';
+
+const result = await db.queryBuilder()
+  .collection('users')
+  .find(builder =>
+    builder.nested('user', nested =>
+      nested.andGroup(() => [
+        LogicalOperator.Condition(
+          nested.field('profile').field('name').equals('John')
+        ),
+        LogicalOperator.Condition(
+          nested.field('settings').field('notifications').isTrue()
+        )
+      ])
+    )
+  )
+  .execute();
+```
+
+## OnChainDB Static Class
+
+For standalone query building without client initialization:
+
+```typescript
+import { OnChainDB, FetchHttpClient } from '@onchaindb/sdk';
+
+// Configure globally
+OnChainDB.configure(new FetchHttpClient(), 'http://localhost:9092', 'api_key');
+
+// Build queries
+const query = OnChainDB.query()
+  .collection('users')
+  .selectAll();
+
+// Execute raw queries
+const result = await OnChainDB.rawQuery('{"find": {}, "select": {}}');
+
+// Query from JSON object
+const result = await OnChainDB.queryFromJson({ find: {}, select: {} });
+
+// Health check
+const isHealthy = await OnChainDB.healthCheck();
+
+// Create indexes
+await OnChainDB.createIndex('my_app', 'users', 'email');
+await OnChainDB.createUniqueIndex('my_app', 'users', 'id');
+
+// Reset configuration
+OnChainDB.reset();
+```
+
+## HTTP Adapters
+
+### Built-in Adapters
+
+```typescript
+import {
+  FetchHttpClient,
+  AxiosHttpClient,
+  NodeHttpClient,
+  createHttpClient
+} from '@onchaindb/sdk';
+
+// Browser (Fetch API)
+const fetchClient = new FetchHttpClient();
+
+// Axios (browser or Node.js)
+const axiosClient = new AxiosHttpClient();
+
+// Node.js native HTTP
+const nodeClient = new NodeHttpClient();
+
+// Auto-detect best client for environment
+const client = createHttpClient();
+```
+
+### Custom HTTP Client
+
+```typescript
+import { HttpClient } from '@onchaindb/sdk';
+
+class CustomHttpClient implements HttpClient {
+  async post(url: string, data: any, headers?: Record<string, string>): Promise<any> {
+    // Your implementation
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...headers },
+      body: JSON.stringify(data)
+    });
+    return response.json();
+  }
+}
+```
+
+## API Reference
+
+### QueryBuilder
+
+| Method | Description |
+|--------|-------------|
+| `collection(name)` | Set target collection |
+| `whereField(name)` | Start a field condition |
+| `find(builderFn)` | Set complex logical conditions |
+| `select(builderFn)` | Configure selection with builder |
+| `selectFields(fields)` | Select specific fields |
+| `selectAll()` | Select all fields |
+| `joinOne(alias, model)` | One-to-one JOIN (returns object/null) |
+| `joinMany(alias, model)` | One-to-many JOIN (returns array) |
+| `joinWith(alias, model)` | JOIN with default behavior |
+| `serverJoin(alias, model, resolve)` | Low-level server JOIN |
+| `limit(n)` | Limit result count |
+| `offset(n)` | Skip results (pagination) |
+| `orderBy(field)` | Sort results |
+| `includeHistory(bool)` | Include historical versions |
+| `withFieldMap(map)` | Set field mapping |
+| `execute()` | Execute query |
+| `executeUnique()` | Execute and return latest record by metadata |
+| `executeWithPayment(quoteId, txHash, network?)` | Execute with x402 payment |
+| `count()` | Count matching records |
+| `sumBy(field)` | Sum numeric field values |
+| `avgBy(field)` | Calculate average of numeric field |
+| `maxBy(field)` | Find maximum value |
+| `minBy(field)` | Find minimum value |
+| `distinctBy(field)` | Get distinct field values |
+| `countDistinct(field)` | Count distinct values |
+| `groupBy(field)` | Start grouped aggregation |
+| `buildRawQuery()` | Get raw query object |
+| `clone()` | Clone the builder |
+| `isValid()` | Check if query has conditions |
+
+### JoinBuilder
+
+| Method | Description |
+|--------|-------------|
+| `onField(name)` | Start JOIN condition |
+| `on(builderFn)` | Complex JOIN condition |
+| `selectFields(fields)` | Select fields from joined collection |
+| `selectAll()` | Select all fields |
+| `selecting(builderFn)` | Configure selection with builder |
+| `joinOne(alias, model)` | Nested one-to-one JOIN |
+| `joinMany(alias, model)` | Nested one-to-many JOIN |
+| `build()` | Complete JOIN and return to parent |
+
+### GroupByQueryBuilder
+
+Returned by `queryBuilder.groupBy(field)`:
+
+| Method | Description |
+|--------|-------------|
+| `count()` | Count records per group |
+| `sumBy(field)` | Sum field values per group |
+| `avgBy(field)` | Average field values per group |
+| `maxBy(field)` | Max field value per group |
+| `minBy(field)` | Min field value per group |
+
+### LogicalOperator
+
+| Static Method | Description |
+|---------------|-------------|
+| `And(conditions)` | Combine with AND logic |
+| `Or(conditions)` | Combine with OR logic |
+| `Not(conditions)` | Negate conditions |
+| `Condition(cond)` | Wrap a field condition |
+
+### SelectionBuilder
+
+| Method | Description |
+|--------|-------------|
+| `field(name)` | Include a field |
+| `fields(names)` | Include multiple fields |
+| `nested(name, builderFn)` | Nested selection |
+| `exclude(name)` | Exclude a field |
+| `excludeFields(names)` | Exclude multiple fields |
+| `build()` | Get selection map |
+| `clear()` | Reset builder |
+| `static all()` | Select all fields |
+
+### QueryResult
+
+| Method | Description |
+|--------|-------------|
+| `len()` / `length()` | Record count |
+| `isEmpty()` | Check if empty |
+| `first()` / `last()` / `get(i)` | Access records |
+| `any(predicate)` | Any match? |
+| `all(predicate)` | All match? |
+| `find(predicate)` | Find first matching |
+| `filter(predicate)` | Filter records |
+| `map(transform)` | Transform records |
+| `forEach(callback)` | Iterate records |
+| `reduce(callback, initial)` | Reduce records |
+| `groupBy(field)` | Group by field value |
+| `pluck(field)` | Extract field values |
+| `summarizeNumeric(field)` | Statistical summary |
+| `sortBy(field, asc?)` | Sort by field |
+| `sortByMultiple(specs)` | Multi-field sort |
+| `paginate(page, size)` | Paginate results |
+| `chunk(size)` | Split into chunks |
+| `distinctBy(field)` | Unique by field |
+| `count(predicate?)` | Count records |
+| `countBy(field)` | Count by field value |
+| `innerJoin(other, thisKey, otherKey)` | Inner join |
+| `leftJoin(other, thisKey, otherKey)` | Left join |
+| `toCsv(delimiter?)` | Export to CSV |
+| `toJSON()` | Export to JSON |
+| `toArray()` | Get plain array |
+| `inspect(limit?)` | Debug output |
+
+## Types
+
+```typescript
+// Query types
+interface QueryRequest {
+  find: any;
+  select: SelectionMap;
+  include_history?: boolean;
+  limit?: number;
+  offset?: number;
+  sort?: string[];
+}
+
+interface QueryResponse<T = any> {
+  records: T[];
+  total?: number;
+  error?: string;
+}
+
+// Value types
+type Val = string | number | boolean | null | Val[] | Date | RegExp;
+
+interface BetweenValue {
+  min: Val;
+  max: Val;
+}
+
+// Numeric summary
+interface NumericSummary {
+  count: number;
+  sum: number;
+  mean: number;
+  median: number;
+  min: number;
+  max: number;
+  standardDeviation: number;
+  variance: number;
+}
+```
+
+---
+
+For complete SDK documentation, see the [main README](../../README.md).