@onchaindb/sdk 0.4.0 → 0.4.2

package/examples/tweet-self-joins-example.ts

@@ -0,0 +1,352 @@
+#!/usr/bin/env ts-node
+/**
+ * Example: Server-Side Self-Referential JOINs for Tweet Collection
+ *
+ * This demonstrates how to use server-side JOINs for tweets that reference other tweets:
+ * - tweet → reply_to_tweet (replies)
+ * - tweet → quote_tweet (quote tweets)
+ * - tweet → retweet_of (retweets)
+ *
+ * These are all self-referential JOINs (tweets joining with tweets)
+ */
+
+import { createClient } from '../src/index';
+import type { ConditionBuilder, LogicalOperator } from '../src/index';
+
+async function demonstrateTweetSelfJoins() {
+    console.log('🐦 Tweet Collection Self-Referential JOINs\n');
+    console.log('='.repeat(70));
+    console.log('');
+
+    // Initialize OnChainDB client
+    const client = createClient({
+        endpoint: 'http://localhost:9092',
+        appId: 'app_c50ae7013e424cfc'
+    });
+
+    // ========================================
+    // Example 1: Get tweets with their replies
+    // ========================================
+    console.log('1️⃣  Get Tweets with Replies (Self-Referential JOIN)\n');
+    console.log('Query: Root tweets that have no reply_to_id, joined with their replies');
+    console.log('');
+
+    const tweetsWithReplies = client.queryBuilder()
+        .collection('tweets')
+        .whereField('reply_to_id').isNull()  // Only root tweets (not replies themselves)
+        // JOIN: Get all tweets that reply to this tweet
+        .joinWith('replies', 'tweets')
+            .onField('reply_to_id').equals('$data.id')  // Join condition: reply_to_id = parent.id
+            .selectFields(['id', 'content', 'author', 'created_at', 'like_count'])
+            .build()
+        .selectFields(['id', 'content', 'author', 'created_at', 'reply_count', 'replies'])
+        .limit(10);
+
+    console.log('Generated Query:');
+    console.log(JSON.stringify(tweetsWithReplies.buildRawQuery(), null, 2));
+    console.log('');
+    console.log('Expected Result Structure:');
+    console.log(`{
+  "records": [
+    {
+      "id": "tweet_123",
+      "content": "Original tweet",
+      "author": "celestia1abc...",
+      "created_at": "2025-01-15T10:00:00Z",
+      "reply_count": 3,
+      "replies": [
+        {
+          "id": "tweet_456",
+          "content": "First reply",
+          "author": "celestia1def...",
+          "created_at": "2025-01-15T10:05:00Z",
+          "like_count": 5
+        },
+        {
+          "id": "tweet_789",
+          "content": "Second reply",
+          "author": "celestia1ghi...",
+          "created_at": "2025-01-15T10:10:00Z",
+          "like_count": 2
+        }
+      ]
+    }
+  ]
+}`);
+    console.log('');
+    console.log('─'.repeat(70));
+    console.log('');
+
+    // ========================================
+    // Example 2: Get a specific tweet with all its replies (Thread View)
+    // ========================================
+    console.log('2️⃣  Get Single Tweet with All Replies (Thread View)\n');
+    console.log('Query: One specific tweet with all replies joined');
+    console.log('');
+
+    const tweetThread = client.queryBuilder()
+        .collection('tweets')
+        .whereField('id').equals('tweet_specific_id_here')
+        // JOIN: Get all replies to this specific tweet
+        .joinWith('replies', 'tweets')
+            .onField('reply_to_id').equals('$data.id')
+            .selectAll()
+            .build()
+        .selectAll()
+        .limit(1);
+
+    console.log('Generated Query:');
+    console.log(JSON.stringify(tweetThread.buildRawQuery(), null, 2));
+    console.log('');
+    console.log('Use Case: Tweet detail page showing the main tweet and all replies');
+    console.log('');
+    console.log('─'.repeat(70));
+    console.log('');
+
+    // ========================================
+    // Example 3: Get tweets with quoted tweets
+    // ========================================
+    console.log('3️⃣  Get Tweets with Quote Tweets (Self-Referential JOIN)\n');
+    console.log('Query: Tweets that quote other tweets');
+    console.log('');
+
+    const tweetsWithQuotes = client.queryBuilder()
+        .collection('tweets')
+        .whereField('quote_tweet_id').isNotNull()  // Only quote tweets
+        // JOIN: Get the original quoted tweet
+        .joinWith('quoted_tweet', 'tweets')
+            .onField('id').equals('$data.quote_tweet_id')  // Join condition: id = quote_tweet_id
+            .selectFields(['id', 'content', 'author', 'like_count', 'created_at'])
+            .build()
+        .selectFields(['id', 'content', 'author', 'quote_tweet_id', 'quoted_tweet', 'created_at'])
+        .limit(20);
+
+    console.log('Generated Query:');
+    console.log(JSON.stringify(tweetsWithQuotes.buildRawQuery(), null, 2));
+    console.log('');
+    console.log('Expected Result Structure:');
+    console.log(`{
+  "records": [
+    {
+      "id": "tweet_999",
+      "content": "Great point! Adding my thoughts...",
+      "author": "celestia1xyz...",
+      "quote_tweet_id": "tweet_777",
+      "quoted_tweet": {
+        "id": "tweet_777",
+        "content": "Original insight about decentralization",
+        "author": "celestia1abc...",
+        "like_count": 42,
+        "created_at": "2025-01-14T15:00:00Z"
+      },
+      "created_at": "2025-01-15T12:00:00Z"
+    }
+  ]
+}`);
+    console.log('');
+    console.log('─'.repeat(70));
+    console.log('');
+
+    // ========================================
+    // Example 4: Multiple Self-Referential JOINs
+    // ========================================
+    console.log('4️⃣  Multiple Self-Referential JOINs (Replies + Quoted Tweets)\n');
+    console.log('Query: Root tweets with both replies AND quoted tweet info');
+    console.log('');
+
+    const complexTweets = client.queryBuilder()
+        .collection('tweets')
+        .whereField('reply_to_id').isNull()
+        // JOIN 1: Get replies
+        .joinWith('replies', 'tweets')
+            .onField('reply_to_id').equals('$data.id')
+            .selectFields(['id', 'content', 'author'])
+            .build()
+        // JOIN 2: Get quoted tweet (if this tweet is a quote)
+        .joinWith('quoted_tweet', 'tweets')
+            .onField('id').equals('$data.quote_tweet_id')
+            .selectFields(['id', 'content', 'author'])
+            .build()
+        .selectAll()
+        .limit(10);
+
+    console.log('Generated Query:');
+    console.log(JSON.stringify(complexTweets.buildRawQuery(), null, 2));
+    console.log('');
+    console.log('Use Case: Full timeline view with all tweet relationships');
+    console.log('');
+    console.log('─'.repeat(70));
+    console.log('');
+
+    // ========================================
+    // Example 5: Nested Replies (Reply Chain)
+    // ========================================
+    console.log('5️⃣  Get Reply Chain (Nested Self-Referential JOINs)\n');
+    console.log('Query: A tweet and its reply, with that reply\'s replies');
+    console.log('Note: This shows the nested JOIN structure');
+    console.log('');
+
+    // Note: For deeply nested replies, you'd need to structure nested JOINs
+    // This is a conceptual example - actual implementation depends on Scepter support
+    const replyChain = client.queryBuilder()
+        .collection('tweets')
+        .whereField('id').equals('tweet_root_id')
+        // Get direct replies to this tweet
+        .serverJoin('replies', 'tweets', {
+            find: {
+                reply_to_id: { is: '$data.id' }
+            },
+            select: {
+                id: true,
+                content: true,
+                author: true,
+                reply_count: true
+                // For nested replies, you'd add another JOIN here
+                // but that requires more complex query structure
+            }
+        })
+        .selectAll()
+        .limit(1);
+
+    console.log('Generated Query:');
+    console.log(JSON.stringify(replyChain.buildRawQuery(), null, 2));
+    console.log('');
+    console.log('For deeper nesting, you would use recursive JOIN resolution in Scepter');
+    console.log('');
+    console.log('─'.repeat(70));
+    console.log('');
+
+    // ========================================
+    // Example 6: Using Direct serverJoin() Method
+    // ========================================
+    console.log('6️⃣  Direct serverJoin() for Advanced Queries\n');
+    console.log('Query: Tweets with replies using direct JSON format');
+    console.log('');
+
+    const directServerJoin = client.queryBuilder()
+        .collection('tweets')
+        .whereField('reply_to_id').isNull()
+        // Use direct serverJoin() method for more control
+        .serverJoin('replies', 'tweets', {
+            find: {
+                reply_to_id: { is: '$data.id' }
+            },
+            select: {
+                id: true,
+                content: true,
+                author: true,
+                like_count: true
+            }
+        })
+        .selectFields(['id', 'content', 'author', 'replies'])
+        .limit(10);
+
+    console.log('Generated Query:');
+    console.log(JSON.stringify(directServerJoin.buildRawQuery(), null, 2));
+    console.log('');
+    console.log('Use Case: When you need precise control over JOIN query structure');
+    console.log('');
+    console.log('─'.repeat(70));
+    console.log('');
+
+    // ========================================
+    // Comparison: Client-Side vs Server-Side JOINs
+    // ========================================
+    console.log('📊 Performance Comparison: Client vs Server JOINs\n');
+    console.log('CLIENT-SIDE JOIN (deprecated .join() method):');
+    console.log('  1. Query main tweets                → HTTP Request 1');
+    console.log('  2. Extract all reply_to_ids         → Client processing');
+    console.log('  3. Query tweets WHERE id IN [...]   → HTTP Request 2');
+    console.log('  4. Merge results in JavaScript      → Client processing');
+    console.log('  Total: 2+ HTTP requests, client-side merging');
+    console.log('');
+    console.log('SERVER-SIDE JOIN (new .joinWith() method):');
+    console.log('  1. Send query with JOIN clause      → HTTP Request 1');
+    console.log('  2. Backend executes recursive JOIN  → Scepter engine');
+    console.log('  3. Return fully resolved data       → Single response');
+    console.log('  Total: 1 HTTP request, server-side optimization');
+    console.log('');
+    console.log('─'.repeat(70));
+    console.log('');
+
+    // ========================================
+    // Migration Guide
+    // ========================================
+    console.log('🔄 Migration from Client-Side to Server-Side JOINs\n');
+    console.log('OLD CODE (client-side):');
+    console.log(`
+const result = await client.queryBuilder()
+    .collection('tweets')
+    .join('tweets', 'id', 'reply_to_id', 'replies')  // DEPRECATED
+    .whereField('reply_to_id').isNull()
+    .execute();
+`);
+    console.log('NEW CODE (server-side):');
+    console.log(`
+const result = await client.queryBuilder()
+    .collection('tweets')
+    .whereField('reply_to_id').isNull()
+    .joinWith('replies', 'tweets')
+        .onField('reply_to_id').equals('$data.id')
+        .selectFields(['id', 'content', 'author'])
+        .build()
+    .execute();
+`);
+    console.log('');
+    console.log('Benefits:');
+    console.log('  ✅ Single HTTP request instead of multiple');
+    console.log('  ✅ Recursive JOIN resolution by Scepter');
+    console.log('  ✅ Indexed lookups (O(log N) performance)');
+    console.log('  ✅ Supports nested JOINs (tweet → reply → reply)');
+    console.log('  ✅ Less client-side JavaScript processing');
+    console.log('');
+    console.log('─'.repeat(70));
+    console.log('');
+
+    // ========================================
+    // Common Patterns
+    // ========================================
+    console.log('📝 Common Tweet JOIN Patterns\n');
+    console.log('');
+    console.log('PATTERN 1: Timeline with Replies');
+    console.log('  .whereField("reply_to_id").isNull()  // Root tweets only');
+    console.log('  .joinWith("replies", "tweets")');
+    console.log('      .onField("reply_to_id").equals("$data.id")');
+    console.log('');
+    console.log('PATTERN 2: Quote Tweets');
+    console.log('  .whereField("quote_tweet_id").isNotNull()  // Only quotes');
+    console.log('  .joinWith("quoted_tweet", "tweets")');
+    console.log('      .onField("id").equals("$data.quote_tweet_id")');
+    console.log('');
+    console.log('PATTERN 3: Thread View');
+    console.log('  .whereField("id").equals(tweetId)  // Specific tweet');
+    console.log('  .joinWith("replies", "tweets")');
+    console.log('      .onField("reply_to_id").equals("$data.id")');
+    console.log('');
+    console.log('PATTERN 4: Filtered Replies');
+    console.log('  .joinWith("verified_replies", "tweets")');
+    console.log('      .on(builder => builder.and([');
+    console.log('          builder.condition("reply_to_id", c => c.equals("$data.id")),');
+    console.log('          builder.condition("like_count", c => c.greaterThan(threshold))');
+    console.log('      ]))');
+    console.log('');
+    console.log('─'.repeat(70));
+    console.log('');
+
+    console.log('🎉 Tweet Self-Referential JOIN Examples Complete!\n');
+    console.log('Next Step: Update RealSocialService.ts to use server-side JOINs');
+    console.log('');
+
+    // Uncomment to actually execute a query:
+    // try {
+    //     console.log('Executing query...');
+    //     const result = await tweetsWithReplies.execute();
+    //     console.log(`\n✅ Query executed: ${result.records.length} records returned`);
+    //     console.log('Sample record:', JSON.stringify(result.records[0], null, 2));
+    // } catch (error) {
+    //     console.error('❌ Query execution failed:', error);
+    // }
+}
+
+// Run the demonstration
+demonstrateTweetSelfJoins().catch(console.error);