@onchaindb/sdk 0.4.5 → 2.0.0

package/src/query-sdk/README.md

@@ -1,248 +1,156 @@
-# OnChainDB Query SDK
+# OnDB 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.
+Fluent API for building queries with server-side JOINs, logical operators, field conditions, and aggregations.
 
 ## 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)
+- [Logical Operators](#logical-operators)
+- [Server-Side JOINs](#server-side-joins)
+- [Aggregations](#aggregations)
 - [Selection](#selection)
-- [QueryResult Utilities](#queryresult-utilities)
 - [Nested Field Queries](#nested-field-queries)
-- [OnChainDB Static Class](#onchaindb-static-class)
+- [QueryResult](#queryresult)
 - [HTTP Adapters](#http-adapters)
 - [API Reference](#api-reference)
 
-## Quick Start
+## QueryBuilder
 
 ```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')
+  .collection('users')              // Target collection
   .whereField('status').equals('active')
-  .selectFields(['id', 'name', 'email'])
-  .limit(10)
+  .selectFields(['id', 'name'])
+  .orderBy('created_at', 'DESC')
+  .limit(50)
+  .offset(100)
   .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.
+Returns the latest record by `updatedAt` / `createdAt` timestamp. Returns `null` if nothing matches.
 
 ```typescript
-// Find the latest user record by email
 const user = await db.queryBuilder()
   .collection('users')
   .whereField('email').equals('alice@example.com')
   .executeUnique<User>();
+```
+
+### buildRawQuery / clone / isValid
+
+```typescript
+// Inspect the raw query object
+const raw = db.queryBuilder()
+  .collection('tweets')
+  .whereField('author').equals('alice')
+  .buildRawQuery();
+
+// Clone a base query and diverge
+const base = db.queryBuilder().collection('users').selectAll();
+const active   = base.clone().whereField('active').isTrue();
+const inactive = base.clone().whereField('active').isFalse();
 
-// Returns: User | null (latest version by timestamp)
+// Check if a query has conditions set
+queryBuilder.isValid(); // false until whereField / find is called
 ```
 
-### WhereField Operators
+## Field Operators
 
-All operators available on `whereField()`:
+All operators available on `whereField()` and `FieldConditionBuilder`:
 
 ```typescript
 // Comparison
-.equals(value)
-.notEquals(value)
-.greaterThan(value)
-.greaterThanOrEqual(value)
-.lessThan(value)
-.lessThanOrEqual(value)
-.between(min, max)
+.equals(value)                 .notEquals(value)
+.greaterThan(value)            .greaterThanOrEqual(value)
+.lessThan(value)               .lessThanOrEqual(value)
+.between(min, max)             // betweenOp: { from, to }
 
 // String
-.contains(value)
-.startsWith(value)
-.endsWith(value)
+.contains(value)               // includes
+.startsWith(value)             .endsWith(value)
 .regExpMatches(pattern)
 .includesCaseInsensitive(value)
 .startsWithCaseInsensitive(value)
 .endsWithCaseInsensitive(value)
 
 // Array
-.in(values)
-.notIn(values)
+.in(values)                    .notIn(values)
 
 // Existence
-.exists()
-.notExists()
-.isNull()
-.isNotNull()
-.isTrue()
-.isFalse()
-
-// IP Address
-.isLocalIp()
-.isExternalIp()
-.inCountry(countryCode)
-.cidr(cidrRange)
-
-// Special
-.b64(value)
-.inDataset(dataset)
+.exists()    .notExists()    .isNull()    .isNotNull()
+.isTrue()    .isFalse()
+
+// Network / security
+.isLocalIp()    .isExternalIp()
+.inCountry(countryCode)        .cidr(cidrRange)
+.b64(value)                    .inDataset(dataset)
 ```
 
-### Debugging
+### FieldConditionBuilder directly
 
 ```typescript
-// Get raw query object for debugging
-const rawQuery = db.queryBuilder()
-  .collection('tweets')
-  .whereField('author').equals('alice')
-  .selectAll()
-  .buildRawQuery();
+import { FieldConditionBuilder } from '@ondb/sdk';
 
-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();
+const condition = new FieldConditionBuilder('user.profile.bio').contains('Developer');
+condition.toComposable(); // { user: { profile: { bio: { includes: 'Developer' } } } }
 ```
 
-## Aggregations
-
-QueryBuilder provides built-in aggregation methods for counting, summing, averaging, and grouping data.
-
-### Basic Aggregations
+## Logical Operators
 
 ```typescript
-// Count records
-const activeUsers = await db.queryBuilder()
-  .collection('users')
-  .whereField('active').equals(true)
-  .count();
-// Returns: number
+import { LogicalOperator } from '@ondb/sdk';
 
-// 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
+const result = await db.queryBuilder()
+  .collection('posts')
+  .find(builder =>
+    LogicalOperator.And([
+      builder.field('published').isTrue(),
+      LogicalOperator.Or([
+        builder.field('category').equals('tech'),
+        builder.field('views').greaterThan(1000)
+      ]),
+      LogicalOperator.Not([
+        builder.field('archived').isTrue()
+      ])
+    ])
+  )
+  .selectAll()
+  .execute();
 ```
 
-### Grouped Aggregations
+`builder.field(name)` returns a `FieldConditionBuilder`. Calling any operator on it (`.equals()`, `.greaterThan()`, etc.) returns a `LogicalOperator` directly — no extra wrapping needed.
 
-Use `groupBy()` to perform aggregations on groups of records:
+### Instance chain methods
 
 ```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 }
+const condition = new FieldConditionBuilder('age').greaterThan(18)
+  .and(new FieldConditionBuilder('active').isTrue());
+// type: 'and', conditions: [age > 18, active = true]
 ```
 
-### Nested Field Grouping
-
-GroupBy supports nested field paths:
+### ConditionBuilder (inside find())
 
 ```typescript
-// Group by nested field
-const ordersByRegion = await db.queryBuilder()
-  .collection('orders')
-  .groupBy('customer.address.region')
-  .sumBy('total');
-// Returns: { "West": 10000, "East": 8500 }
+const result = await db.queryBuilder()
+  .collection('users')
+  .find(builder => {
+    const isAdult   = builder.field('age').greaterThan(18);
+    const isActive  = builder.field('status').equals('active');
+    return builder.and(isAdult, isActive);
+  })
+  .execute();
 ```
 
 ## Server-Side JOINs
 
-Server-side JOINs execute on the backend in a single request. Use `$data.fieldname` to reference parent record fields.
+JOINs run on the backend in a single request. Use `$data.fieldname` to reference fields from the parent record.
 
-### joinOne (One-to-One)
+### joinOne (one-to-one)
 
-Returns a single object or null. Use when you expect at most one related record.
+Returns a single object or `null`.
 
 ```typescript
 const result = await db.queryBuilder()
@@ -254,12 +162,12 @@ const result = await db.queryBuilder()
   .selectAll()
   .execute();
 
-// Result: { id, content, author, author_info: { display_name, ... } | null }
+// record.author_info => { display_name, avatar_url, verified } | null
 ```
 
-### joinMany (One-to-Many)
+### joinMany (one-to-many)
 
-Returns an array of related records. Use when you expect multiple related records.
+Returns an array.
 
 ```typescript
 const result = await db.queryBuilder()
@@ -271,22 +179,7 @@ const result = await db.queryBuilder()
   .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();
+// record.tweets => [{ id, content, created_at }, ...]
 ```
 
 ### Multiple JOINs
@@ -295,17 +188,14 @@ const result = await db.queryBuilder()
 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'])
@@ -317,18 +207,15 @@ const result = await db.queryBuilder()
 
 ### Nested JOINs
 
-Chain JOINs before calling `.build()` to create nested relationships:
+Chain JOINs before `.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')
+    .joinOne('author_info', 'users')        // Nested: author for each reply
       .onField('address').equals('$data.author')
       .selectFields(['display_name', 'avatar_url'])
       .build()
@@ -337,272 +224,114 @@ const result = await db.queryBuilder()
   .execute();
 ```
 
-### Self-Referential JOINs
+### JoinBuilder Operators (on `onField()`)
 
 ```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();
+.equals(value)    .in(values)
+.greaterThan(v)   .lessThan(v)
+.isNull()         .isNotNull()
 ```
 
-### JoinBuilder Operators
+## Aggregations
 
-Available on `onField()`:
+All aggregations execute server-side.
 
-```typescript
-.equals(value)
-.in(values)
-.greaterThan(value)
-.lessThan(value)
-.isNull()
-.isNotNull()
-```
+### Basic Aggregations
 
-## Logical Operators
+```typescript
+// Count
+const n = await db.queryBuilder()
+  .collection('users')
+  .whereField('active').isTrue()
+  .count();
 
-Build complex conditions with AND, OR, and NOT:
+// Sum / average / max / min
+const total = await db.queryBuilder().collection('orders').sumBy('amount');
+const avg   = await db.queryBuilder().collection('orders').avgBy('amount');
+const max   = await db.queryBuilder().collection('products').maxBy('price');
+const min   = await db.queryBuilder().collection('products').minBy('price');
 
-```typescript
-import { LogicalOperator } from '@onchaindb/sdk';
+// Distinct values
+const categories = await db.queryBuilder().collection('products').distinctBy('category');
 
-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();
+// Count distinct
+const n = await db.queryBuilder().collection('products').countDistinct('category');
 ```
 
-### ConditionBuilder Methods
+### Grouped Aggregations
+
+`groupBy(field)` returns a `GroupByQueryBuilder` with the same aggregate 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'))
-  ])
-)
-```
+// Count per group
+const byCountry = await db.queryBuilder()
+  .collection('users')
+  .groupBy('country')
+  .count();
+// { "USA": 150, "UK": 75, "Germany": 50 }
 
-## Field Operators
+// Sum per group
+const salesByCategory = await db.queryBuilder()
+  .collection('orders')
+  .whereField('status').equals('completed')
+  .groupBy('category')
+  .sumBy('amount');
+// { "electronics": 50000, "clothing": 25000 }
 
-### FieldConditionBuilder
+// Supports nested field paths
+const byRegion = await db.queryBuilder()
+  .collection('orders')
+  .groupBy('customer.address.region')
+  .sumBy('total');
+```
+
+## Selection
 
-All available operators:
+### selectFields / selectAll
 
 ```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)
+db.queryBuilder().collection('users').selectFields(['id', 'name', 'email']).execute();
+db.queryBuilder().collection('users').selectAll().execute();
 ```
 
-## Selection
-
 ### SelectionBuilder
 
 ```typescript
-import { SelectionBuilder } from '@onchaindb/sdk';
+import { SelectionBuilder } from '@ondb/sdk';
 
-// Select specific fields
-const selection = new SelectionBuilder()
-  .field('id')
-  .field('name')
-  .field('email')
-  .build();
+// Field-by-field
+const sel = new SelectionBuilder().field('id').field('name').build();
 
-// Select multiple fields at once
-new SelectionBuilder()
-  .fields(['id', 'name', 'email', 'created_at'])
-  .build();
+// Multiple at once
+new SelectionBuilder().fields(['id', 'name', 'email']).build();
 
-// Nested field selection
+// Nested selection
 new SelectionBuilder()
   .field('id')
-  .nested('profile', nested => nested.field('bio').field('avatar'))
+  .nested('profile', n => n.field('bio').field('avatar'))
   .build();
 
 // Exclude fields
-new SelectionBuilder()
-  .excludeFields(['password', 'secret_key'])
-  .build();
+new SelectionBuilder().excludeFields(['password', 'secret']).build();
 
-// Select all fields
-SelectionBuilder.all();  // Returns {}
+// Select all
+SelectionBuilder.all(); // {}
 ```
 
-### Using with QueryBuilder
+### select() with builder
 
 ```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
+### Dot notation
 
 ```typescript
-// Query nested fields with dot notation
 const result = await db.queryBuilder()
   .collection('users')
   .whereField('profile.settings.theme').equals('dark')
@@ -610,99 +339,68 @@ const result = await db.queryBuilder()
   .execute();
 ```
 
-### ORM-like Nested Builder
+### NestedConditionBuilder
 
 ```typescript
-import { NestedConditionBuilder, LogicalOperator } from '@onchaindb/sdk';
+import { NestedConditionBuilder } from '@ondb/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()
-        )
+      nested.andGroup(b => [
+        b.field('name').equals('John'),
+        b.field('status').equals('active')
       ])
     )
   )
   .execute();
 ```
 
-## OnChainDB Static Class
+## QueryResult
 
-For standalone query building without client initialization:
+A lightweight wrapper around query response data for convenient access. Aggregation, sorting, filtering, and joining are handled server-side via `QueryBuilder`.
 
 ```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": {}}');
+import { createQueryResult } from '@ondb/sdk';
 
-// 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');
+const result = createQueryResult(response.records);
 
-// Reset configuration
-OnChainDB.reset();
+result.len()          // Total record count
+result.length()       // Alias for len()
+result.isEmpty()      // true if no records
+result.first()        // First record or undefined
+result.last()         // Last record or undefined
+result.get(2)         // Record at index or undefined
+result.toArray()      // Plain array copy
+result.toJSON()       // JSON string
+result.cast<User>()   // Re-type without copying
 ```
 
 ## 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();
+  FetchHttpClient,   // Browser Fetch API
+  AxiosHttpClient,   // Axios (browser or Node.js)
+  NodeHttpClient,    // Node.js native HTTP
+  createHttpClient   // Auto-detect best for environment
+} from '@ondb/sdk';
 ```
 
 ### Custom HTTP Client
 
 ```typescript
-import { HttpClient } from '@onchaindb/sdk';
+import { HttpClient } from '@ondb/sdk';
 
-class CustomHttpClient implements HttpClient {
+class MyHttpClient implements HttpClient {
   async post(url: string, data: any, headers?: Record<string, string>): Promise<any> {
-    // Your implementation
-    const response = await fetch(url, {
+    const res = await fetch(url, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json', ...headers },
       body: JSON.stringify(data)
     });
-    return response.json();
+    return res.json();
   }
 }
 ```
@@ -714,68 +412,61 @@ class CustomHttpClient implements HttpClient {
 | Method | Description |
 |--------|-------------|
 | `collection(name)` | Set target collection |
-| `whereField(name)` | Start a field condition |
+| `whereField(name)` | Start a field condition (returns `WhereClause`) |
 | `find(builderFn)` | Set complex logical conditions |
-| `select(builderFn)` | Configure selection with builder |
+| `select(builderFn)` | Configure selection with `SelectionBuilder` |
 | `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 |
+| `joinOne(alias, model)` | One-to-one server JOIN |
+| `joinMany(alias, model)` | One-to-many server JOIN |
+| `joinWith(alias, model)` | Server JOIN with default array behavior |
+| `orderBy(field, dir?)` | Sort (`'ASC'` or `'DESC'`) |
 | `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 |
+| `offset(n)` | Skip results |
+| `includeHistory(bool)` | Include all historical versions |
+| `execute()` | Execute and return records |
+| `executeUnique()` | Return latest single record or `null` |
 | `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 |
+| `avgBy(field)` | Average numeric field values |
+| `maxBy(field)` | Maximum field value |
+| `minBy(field)` | Minimum field value |
+| `distinctBy(field)` | Distinct field values |
 | `countDistinct(field)` | Count distinct values |
 | `groupBy(field)` | Start grouped aggregation |
-| `buildRawQuery()` | Get raw query object |
+| `buildRawQuery()` | Inspect raw query object |
 | `clone()` | Clone the builder |
-| `isValid()` | Check if query has conditions |
+| `isValid()` | `true` 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 |
+| `selectFields(fields)` | Select from joined collection |
+| `selectAll()` | Select all from joined collection |
+| `selecting(builderFn)` | Selection via `SelectionBuilder` |
 | `joinOne(alias, model)` | Nested one-to-one JOIN |
 | `joinMany(alias, model)` | Nested one-to-many JOIN |
-| `build()` | Complete JOIN and return to parent |
+| `build()` | Complete JOIN, 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 |
+| `count()` | Count per group |
+| `sumBy(field)` | Sum per group |
+| `avgBy(field)` | Average per group |
+| `maxBy(field)` | Max per group |
+| `minBy(field)` | Min per group |
 
-### LogicalOperator
+### LogicalOperator (static)
 
-| 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 |
+| Method | Description |
+|--------|-------------|
+| `And(conditions)` | AND of conditions |
+| `Or(conditions)` | OR of conditions |
+| `Not(conditions)` | NOT of conditions |
 
 ### SelectionBuilder
 
@@ -783,83 +474,23 @@ Returned by `queryBuilder.groupBy(field)`:
 |--------|-------------|
 | `field(name)` | Include a field |
 | `fields(names)` | Include multiple fields |
-| `nested(name, builderFn)` | Nested selection |
+| `nested(name, fn)` | Nested field selection |
 | `exclude(name)` | Exclude a field |
 | `excludeFields(names)` | Exclude multiple fields |
 | `build()` | Get selection map |
-| `clear()` | Reset builder |
-| `static all()` | Select all fields |
+| `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;
-}
-```
+| `isEmpty()` | `true` if no records |
+| `first()` / `last()` | First or last record |
+| `get(index)` | Record at index |
+| `toArray()` | Plain array copy |
+| `toJSON()` | JSON string |
+| `cast<T>()` | Re-type the result |
 
 ---