@onchaindb/sdk 0.4.0 → 0.4.2

package/examples/collection-schema-example.ts

@@ -0,0 +1,304 @@
+/**
+ * OnChainDB SDK - Collection Schema Example
+ *
+ * Demonstrates how to create collections with schemas and indexes
+ * using the simplified createCollection API.
+ */
+
+import { createClient, OnChainDBError, SimpleCollectionSchema } from '../src';
+
+async function createCollectionExample() {
+    console.log('OnChainDB SDK - Collection Schema Example\n');
+
+    const db = createClient({
+        endpoint: 'http://localhost:9092',
+        appKey: 'your_app_key',
+        appId: 'my_app'
+    });
+
+    try {
+        // 1. Create a users collection with schema
+        console.log('1. Creating users collection...');
+
+        const usersSchema: SimpleCollectionSchema = {
+            name: 'users',
+            fields: {
+                email: { type: 'string', index: true },
+                username: { type: 'string', index: true },
+                age: { type: 'number' },  // not indexed
+                isActive: { type: 'boolean', index: true },
+                joinedAt: { type: 'date', index: true }
+            },
+            useBaseFields: true // adds id, createdAt, updatedAt, deletedAt indexes
+        };
+
+        const usersResult = await db.createCollection(usersSchema);
+
+        console.log(`   Collection: ${usersResult.collection}`);
+        console.log(`   Success: ${usersResult.success}`);
+        console.log(`   Indexes created:`);
+        usersResult.indexes.forEach(idx => {
+            console.log(`     - ${idx.field} (${idx.type}): ${idx.status}`);
+        });
+        if (usersResult.warnings?.length) {
+            console.log(`   Warnings: ${usersResult.warnings.join(', ')}`);
+        }
+        console.log();
+
+        // 2. Create a posts collection with monetization
+        console.log('2. Creating posts collection with read pricing...');
+
+        const postsSchema: SimpleCollectionSchema = {
+            name: 'posts',
+            fields: {
+                title: { type: 'string', index: true },
+                content: {
+                    type: 'string',
+                    index: true,
+                    readPricing: {
+                        pricePerAccess: 0.001 // 0.001 TIA per read
+                    }
+                },
+                authorId: { type: 'string', index: true },
+                likes: { type: 'number', index: true },
+                publishedAt: { type: 'date', index: true },
+                tags: { type: 'string', index: true } // for tag-based queries
+            },
+            useBaseFields: true
+        };
+
+        const postsResult = await db.createCollection(postsSchema);
+
+        console.log(`   Collection: ${postsResult.collection}`);
+        console.log(`   Success: ${postsResult.success}`);
+        console.log(`   Indexes: ${postsResult.indexes.length} created`);
+        console.log();
+
+        // 3. Create a minimal collection without base fields
+        console.log('3. Creating events collection (no base fields)...');
+
+        const eventsSchema: SimpleCollectionSchema = {
+            name: 'events',
+            fields: {
+                eventType: { type: 'string', index: true },
+                timestamp: { type: 'date', index: true },
+                data: { type: 'string' } // not indexed
+            },
+            useBaseFields: false // only custom fields
+        };
+
+        const eventsResult = await db.createCollection(eventsSchema);
+
+        console.log(`   Collection: ${eventsResult.collection}`);
+        console.log(`   Indexes: ${eventsResult.indexes.length} (no base fields)`);
+        console.log();
+
+        // 4. Now store some data
+        console.log('4. Storing a user...');
+
+        const user = await db.createDocument('users', {
+            email: 'alice@example.com',
+            username: 'alice',
+            age: 28,
+            isActive: true,
+            joinedAt: new Date().toISOString()
+        });
+
+        console.log(`   Created user: ${user.id}`);
+        console.log(`   Email: ${user.email}`);
+        console.log(`   CreatedAt: ${user.createdAt}`);
+        console.log();
+
+        // 5. Query users efficiently (uses indexes)
+        console.log('5. Querying active users...');
+
+        const activeUsers = await db.findMany('users', { isActive: true });
+        console.log(`   Found ${activeUsers.length} active users`);
+        console.log();
+
+        // 6. Sync collection - add/remove indexes based on schema changes
+        console.log('6. Syncing users collection with updated schema...');
+
+        const updatedUsersSchema: SimpleCollectionSchema = {
+            name: 'users',
+            fields: {
+                email: { type: 'string', index: true },
+                username: { type: 'string', index: true },
+                age: { type: 'number', index: true },  // NEW: now indexed
+                isActive: { type: 'boolean', index: true },
+                // joinedAt removed from indexed fields
+                lastLogin: { type: 'date', index: true } // NEW field with index
+            },
+            useBaseFields: true
+        };
+
+        const syncResult = await db.syncCollection(updatedUsersSchema);
+
+        console.log(`   Collection: ${syncResult.collection}`);
+        console.log(`   Success: ${syncResult.success}`);
+        console.log(`   Created: ${syncResult.created.map(i => i.field).join(', ') || 'none'}`);
+        console.log(`   Removed: ${syncResult.removed.map(i => i.field).join(', ') || 'none'}`);
+        console.log(`   Unchanged: ${syncResult.unchanged.length} indexes`);
+        if (syncResult.errors?.length) {
+            console.log(`   Errors: ${syncResult.errors.join(', ')}`);
+        }
+
+        console.log('\nAll collection operations completed!');
+
+    } catch (error) {
+        if (error instanceof OnChainDBError) {
+            console.error('OnChainDB Error:', error.code, error.message);
+        } else {
+            console.error('Error:', error);
+        }
+    }
+}
+
+// Example: E-commerce schema
+async function ecommerceSchemaExample() {
+    console.log('\nOnChainDB SDK - E-commerce Schema Example\n');
+
+    const db = createClient({
+        endpoint: 'http://localhost:9092',
+        appKey: 'your_app_key',
+        appId: 'ecommerce_app'
+    });
+
+    // Products collection
+    const productsSchema: SimpleCollectionSchema = {
+        name: 'products',
+        fields: {
+            sku: { type: 'string', index: true },
+            name: { type: 'string', index: true },
+            price: { type: 'number', index: true },
+            category: { type: 'string', index: true },
+            inStock: { type: 'boolean', index: true }
+        }
+    };
+
+    // Orders collection with price index for payment splits
+    const ordersSchema: SimpleCollectionSchema = {
+        name: 'orders',
+        fields: {
+            orderNumber: { type: 'string', index: true },
+            customerId: { type: 'string', index: true },
+            status: { type: 'string', index: true },
+            total: {
+                type: 'number',
+                index: true,
+                indexType: 'price' // Price index for automatic payment splits (percentages auto-configured)
+            },
+            orderDate: { type: 'date', index: true }
+        }
+    };
+
+    // Customers collection with nested field indexes
+    const customersSchema: SimpleCollectionSchema = {
+        name: 'customers',
+        fields: {
+            email: { type: 'string', index: true },
+            name: { type: 'string', index: true },
+            tier: { type: 'string', index: true }, // bronze, silver, gold
+            // Nested field indexes using dot notation
+            'address.city': { type: 'string', index: true },
+            'address.country': { type: 'string', index: true },
+            'address.zipCode': { type: 'string', index: true }
+        }
+    };
+
+    console.log('Creating e-commerce collections...');
+
+    const results = await Promise.all([
+        db.createCollection(productsSchema),
+        db.createCollection(ordersSchema),
+        db.createCollection(customersSchema)
+    ]);
+
+    results.forEach(result => {
+        const status = result.success ? '✓' : '✗';
+        console.log(`${status} ${result.collection}: ${result.indexes.length} indexes`);
+    });
+
+    console.log('\nE-commerce schema ready!');
+}
+
+// Example: Social media schema
+async function socialMediaSchemaExample() {
+    console.log('\nOnChainDB SDK - Social Media Schema Example\n');
+
+    const db = createClient({
+        endpoint: 'http://localhost:9092',
+        appKey: 'your_app_key',
+        appId: 'social_app'
+    });
+
+    // Users collection
+    const usersSchema: SimpleCollectionSchema = {
+        name: 'users',
+        fields: {
+            handle: { type: 'string', index: true },
+            displayName: { type: 'string', index: true },
+            verified: { type: 'boolean', index: true },
+            followerCount: { type: 'number', index: true }
+        }
+    };
+
+    // Posts with content monetization
+    const postsSchema: SimpleCollectionSchema = {
+        name: 'posts',
+        fields: {
+            authorHandle: { type: 'string', index: true },
+            content: {
+                type: 'string',
+                index: true,
+                readPricing: { pricePerAccess: 0.0001 } // micro-payment per view
+            },
+            replyToId: { type: 'string', index: true }, // for threading
+            likeCount: { type: 'number', index: true },
+            repostCount: { type: 'number', index: true }
+        }
+    };
+
+    // Follows (lightweight, no base fields)
+    const followsSchema: SimpleCollectionSchema = {
+        name: 'follows',
+        fields: {
+            followerHandle: { type: 'string', index: true },
+            followingHandle: { type: 'string', index: true }
+        },
+        useBaseFields: false // lightweight, just the relation
+    };
+
+    console.log('Creating social media collections...');
+
+    const results = await Promise.all([
+        db.createCollection(usersSchema),
+        db.createCollection(postsSchema),
+        db.createCollection(followsSchema)
+    ]);
+
+    results.forEach(result => {
+        const status = result.success ? '✓' : '✗';
+        console.log(`${status} ${result.collection}: ${result.indexes.length} indexes`);
+    });
+
+    console.log('\nSocial media schema ready!');
+}
+
+// Run examples
+async function main() {
+    await createCollectionExample();
+    // Uncomment to run additional examples:
+    // await ecommerceSchemaExample();
+    // await socialMediaSchemaExample();
+}
+
+if (require.main === module) {
+    main().catch(console.error);
+}
+
+export {
+    createCollectionExample,
+    ecommerceSchemaExample,
+    socialMediaSchemaExample
+};

package/examples/server-side-joins.ts

@@ -0,0 +1,201 @@
+#!/usr/bin/env ts-node
+/**
+ * OnChainDB SDK - Server-Side JOINs Examples
+ *
+ * Server-side JOINs are executed by the backend (Scepter) and support:
+ * - joinOne: One-to-one relationships (returns object or null)
+ * - joinMany: One-to-many relationships (returns array)
+ * - Nested JOINs for deep relationships
+ * - Self-referential JOINs (e.g., tweets referencing tweets)
+ * - Single HTTP request (no N+1 queries)
+ */
+
+import { createClient } from '../src';
+
+async function demonstrateServerSideJoins() {
+  console.log('OnChainDB Server-Side JOIN Examples\n');
+  console.log('='.repeat(60));
+
+  // Initialize client
+  const client = createClient({
+    endpoint: 'http://localhost:9092',
+    appId: 'twitter_app'
+  });
+
+  // ========================================
+  // Example 1: Simple One-to-One JOIN
+  // ========================================
+  console.log('\n1. One-to-One JOIN: Tweets with Author Profile\n');
+
+  const tweetsWithAuthor = client.queryBuilder()
+    .collection('tweets')
+    .whereField('reply_to_id').isNull()
+    .joinOne('author_info', 'users')
+      .onField('address').equals('$data.author')
+      .selectFields(['address', 'display_name', 'avatar_url', 'verified'])
+      .build()
+    .selectFields(['id', 'content', 'author', 'created_at', 'author_info'])
+    .limit(10);
+
+  console.log('Query:');
+  console.log(JSON.stringify(tweetsWithAuthor.buildRawQuery(), null, 2));
+  console.log();
+
+  // ========================================
+  // Example 2: One-to-Many JOIN
+  // ========================================
+  console.log('2. One-to-Many JOIN: Users with Their Tweets\n');
+
+  const usersWithTweets = client.queryBuilder()
+    .collection('users')
+    .joinMany('user_tweets', 'tweets')
+      .onField('author').equals('$data.address')
+      .selectFields(['id', 'content', 'created_at', 'like_count'])
+      .build()
+    .selectAll()
+    .limit(5);
+
+  console.log('Query:');
+  console.log(JSON.stringify(usersWithTweets.buildRawQuery(), null, 2));
+  console.log();
+
+  // ========================================
+  // Example 3: Multiple JOINs
+  // ========================================
+  console.log('3. Multiple JOINs: Timeline with Likes, Replies, Author\n');
+
+  const timeline = client.queryBuilder()
+    .collection('tweets')
+    .whereField('reply_to_id').isNull()
+    // JOIN 1: Author profile
+    .joinOne('author_info', 'users')
+      .onField('address').equals('$data.author')
+      .selectFields(['display_name', 'avatar_url', 'verified'])
+      .build()
+    // JOIN 2: All likes
+    .joinMany('likes', 'likes')
+      .onField('tweet_id').equals('$data.id')
+      .selectFields(['user', 'created_at'])
+      .build()
+    // JOIN 3: All replies
+    .joinMany('replies', 'tweets')
+      .onField('reply_to_id').equals('$data.id')
+      .selectFields(['id', 'author', 'content'])
+      .build()
+    .selectAll()
+    .limit(20);
+
+  console.log('Query:');
+  console.log(JSON.stringify(timeline.buildRawQuery(), null, 2));
+  console.log();
+
+  // ========================================
+  // Example 4: Nested JOINs
+  // ========================================
+  console.log('4. Nested JOINs: Replies with Their Authors\n');
+
+  const tweetWithReplies = client.queryBuilder()
+    .collection('tweets')
+    .whereField('id').equals('tweet_123')
+    // JOIN with nested JOIN inside
+    .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', 'verified'])
+        .build()
+      .build()
+    .selectAll()
+    .limit(1);
+
+  console.log('Query:');
+  console.log(JSON.stringify(tweetWithReplies.buildRawQuery(), null, 2));
+  console.log();
+
+  // ========================================
+  // Example 5: Self-Referential JOIN (Quote Tweets)
+  // ========================================
+  console.log('5. Self-Referential JOIN: Tweets with Quoted Tweet\n');
+
+  const quoteTweets = client.queryBuilder()
+    .collection('tweets')
+    .whereField('quote_tweet_id').isNotNull()
+    // JOIN tweet to itself via quote_tweet_id
+    .joinOne('quote_tweet', 'tweets')
+      .onField('id').equals('$data.quote_tweet_id')
+      .selectFields(['id', 'content', 'author', 'created_at'])
+      // Nested: get quoted tweet's author
+      .joinOne('author_info', 'users')
+        .onField('address').equals('$data.author')
+        .selectFields(['display_name', 'avatar_url'])
+        .build()
+      .build()
+    .selectAll()
+    .limit(10);
+
+  console.log('Query:');
+  console.log(JSON.stringify(quoteTweets.buildRawQuery(), null, 2));
+  console.log();
+
+  // ========================================
+  // Example 6: User Profile with Everything
+  // ========================================
+  console.log('6. Complex Query: User Profile with Tweets, Followers, Following\n');
+
+  const userProfile = client.queryBuilder()
+    .collection('users')
+    .whereField('address').equals('celestia1abc...')
+    // All user's tweets
+    .joinMany('tweets', 'tweets')
+      .onField('author').equals('$data.address')
+      .selectAll()
+      .build()
+    // All followers
+    .joinMany('followers', 'follows')
+      .onField('following').equals('$data.address')
+      .selectFields(['follower', 'created_at'])
+      .build()
+    // All following
+    .joinMany('following', 'follows')
+      .onField('follower').equals('$data.address')
+      .selectFields(['following', 'created_at'])
+      .build()
+    .selectAll()
+    .limit(1);
+
+  console.log('Query:');
+  console.log(JSON.stringify(userProfile.buildRawQuery(), null, 2));
+  console.log();
+
+  // ========================================
+  // Key Points
+  // ========================================
+  console.log('='.repeat(60));
+  console.log('\nKey Points:\n');
+  console.log('- Use $data.fieldname to reference parent record fields');
+  console.log('- joinOne returns object or null (one-to-one)');
+  console.log('- joinMany returns array (one-to-many)');
+  console.log('- Nested JOINs chain with .joinOne()/.joinMany() before .build()');
+  console.log('- All JOINs execute server-side in a single request');
+  console.log('- Call .build() to close each JOIN definition');
+  console.log();
+
+  // ========================================
+  // Execute a query (uncomment to run)
+  // ========================================
+  // try {
+  //   console.log('Executing timeline query...');
+  //   const result = await timeline.execute();
+  //   console.log(`Found ${result.records?.length || 0} tweets`);
+  //   if (result.records?.length > 0) {
+  //     console.log('First tweet:', JSON.stringify(result.records[0], null, 2));
+  //   }
+  // } catch (error) {
+  //   console.error('Query failed:', error);
+  // }
+}
+
+// Run demonstration
+demonstrateServerSideJoins().catch(console.error);