@onchaindb/sdk 0.4.0 → 0.4.2

package/src/query-sdk/NestedBuilders.ts

@@ -0,0 +1,186 @@
+import { LogicalOperator, FieldConditionBuilder, Condition } from './operators';
+
+// Builder for creating nested field conditions with ORM-like syntax
+export class NestedConditionBuilder {
+    private path: string[];
+
+    constructor(rootField: string) {
+        this.path = [rootField];
+    }
+
+    // Add another level to the path and create field conditions
+    field(fieldName: string): NestedFieldConditionBuilder {
+        const newPath = [...this.path, fieldName];
+        return new NestedFieldConditionBuilder(newPath);
+    }
+
+    // Create nested structure with callback
+    nested(fieldName: string, builderFn: (builder: NestedConditionBuilder) => LogicalOperator): LogicalOperator {
+        const nestedPath = [...this.path, fieldName];
+        const nestedBuilder = new NestedConditionBuilder('');
+        nestedBuilder.path = nestedPath;
+        return builderFn(nestedBuilder);
+    }
+
+    // Create logical groups
+    andGroup(builderFn: (builder: NestedConditionBuilder) => LogicalOperator[]): LogicalOperator {
+        const conditions = builderFn(this);
+        return LogicalOperator.And(conditions);
+    }
+
+    orGroup(builderFn: (builder: NestedConditionBuilder) => LogicalOperator[]): LogicalOperator {
+        const conditions = builderFn(this);
+        return LogicalOperator.Or(conditions);
+    }
+
+    notGroup(builderFn: (builder: NestedConditionBuilder) => LogicalOperator[]): LogicalOperator {
+        const conditions = builderFn(this);
+        return LogicalOperator.Not(conditions);
+    }
+}
+
+// Builder for field conditions within nested structures
+// Only includes operators that actually exist in the Rust implementation
+export class NestedFieldConditionBuilder {
+    private fieldPath: string[];
+
+    constructor(fieldPath: string[]) {
+        this.fieldPath = fieldPath;
+    }
+
+    private createCondition(operator: string, value: any): Condition {
+        const path = this.fieldPath.join('.');
+        return {
+            field: path,
+            operator,
+            value
+        };
+    }
+
+    // ===== BASE OPERATORS (BaseOperator) =====
+
+    equals(value: any): Condition {
+        return this.createCondition('is', value);
+    }
+
+    notEquals(value: any): Condition {
+        return this.createCondition('isNot', value);
+    }
+
+    in(values: any[]): Condition {
+        return this.createCondition('in', values);
+    }
+
+    notIn(values: any[]): Condition {
+        return this.createCondition('notIn', values);
+    }
+
+    isNull(): Condition {
+        return this.createCondition('isNull', true);
+    }
+
+    isNotNull(): Condition {
+        return this.createCondition('isNull', false);
+    }
+
+    exists(): Condition {
+        return this.createCondition('exists', true);
+    }
+
+    notExists(): Condition {
+        return this.createCondition('exists', false);
+    }
+
+    // ===== STRING OPERATORS (StringOperator) =====
+
+    startsWith(value: string): Condition {
+        return this.createCondition('startsWith', value);
+    }
+
+    endsWith(value: string): Condition {
+        return this.createCondition('endsWith', value);
+    }
+
+    contains(value: string): Condition {
+        return this.createCondition('includes', value);
+    }
+
+    regExpMatches(pattern: string): Condition {
+        return this.createCondition('regExpMatches', pattern);
+    }
+
+    includesCaseInsensitive(value: string): Condition {
+        return this.createCondition('includesCaseInsensitive', value);
+    }
+
+    startsWithCaseInsensitive(value: string): Condition {
+        return this.createCondition('startsWithCaseInsensitive', value);
+    }
+
+    endsWithCaseInsensitive(value: string): Condition {
+        return this.createCondition('endsWithCaseInsensitive', value);
+    }
+
+    // ===== NUMBER OPERATORS (NumberOperator) =====
+
+    greaterThan(value: any): Condition {
+        return this.createCondition('greaterThan', value);
+    }
+
+    lessThan(value: any): Condition {
+        return this.createCondition('lessThan', value);
+    }
+
+    greaterThanOrEqual(value: any): Condition {
+        return this.createCondition('greaterThanOrEqual', value);
+    }
+
+    lessThanOrEqual(value: any): Condition {
+        return this.createCondition('lessThanOrEqual', value);
+    }
+
+    // ===== IP OPERATORS (IpOperator) =====
+
+    isLocalIp(): Condition {
+        return this.createCondition('isLocalIp', true);
+    }
+
+    isExternalIp(): Condition {
+        return this.createCondition('isExternalIp', true);
+    }
+
+    // ===== MISC OPERATORS (MiscOperator) =====
+
+    b64(value: string): Condition {
+        return this.createCondition('b64', value);
+    }
+
+    inDataset(dataset: string): Condition {
+        return this.createCondition('inDataset', dataset);
+    }
+
+    inCountry(countryCode: string): Condition {
+        return this.createCondition('inCountry', countryCode);
+    }
+
+    cidr(cidr: string): Condition {
+        return this.createCondition('CIDR', cidr);
+    }
+
+    // ===== BETWEEN OPERATOR =====
+
+    between(min: any, max: any): Condition {
+        return this.createCondition('between', { from: min, to: max });
+    }
+
+    // ===== CONVENIENCE METHODS =====
+
+    // Boolean checks (using base operators)
+    isTrue(): Condition {
+        return this.equals(true);
+    }
+
+    isFalse(): Condition {
+        return this.equals(false);
+    }
+}

package/src/query-sdk/OnChainDB.ts

@@ -0,0 +1,294 @@
+import {QueryBuilder} from './QueryBuilder';
+import {SelectionBuilder} from './SelectionBuilder';
+import {FieldMap, HttpClient, QueryRequest, QueryResponse, QueryValue} from "./index";
+
+// Main SDK class providing static methods for query building
+export class OnChainDB {
+    private static httpClient?: HttpClient;
+    private static serverUrl?: string;
+    private static apiKey?: string;
+
+    // Configure the SDK with HTTP client and server URL
+    static configure(httpClient: HttpClient, serverUrl: string, apiKey?: string): void {
+        this.httpClient = httpClient;
+        this.serverUrl = serverUrl;
+        this.apiKey = apiKey;
+    }
+
+    // Get the configured HTTP client
+    static getHttpClient(): HttpClient | undefined {
+        return this.httpClient;
+    }
+
+    // Get the configured server URL
+    static getServerUrl(): string | undefined {
+        return this.serverUrl;
+    }
+
+    // Start building a new query
+    static query(): QueryBuilder {
+        return new QueryBuilder(this.httpClient, this.serverUrl);
+    }
+
+    // Create a query builder with specific HTTP client and server URL (one-time use)
+    static queryWith(httpClient: HttpClient, serverUrl: string): QueryBuilder {
+        return new QueryBuilder(httpClient, serverUrl);
+    }
+
+    // Create a simple query with just field selection (no filtering)
+    static select(builderFn: (builder: SelectionBuilder) => SelectionBuilder): QueryBuilder {
+        const query = new QueryBuilder(this.httpClient, this.serverUrl);
+        query.select(builderFn);
+        return query;
+    }
+
+    // Execute a raw query using HTTP
+    static async rawQuery(
+        queryJson: string,
+        httpClient?: HttpClient,
+        serverUrl?: string,
+        fieldMap?: FieldMap
+    ): Promise<QueryResponse> {
+        const client = httpClient || this.httpClient;
+        const url = serverUrl || this.serverUrl;
+
+        if (!client) {
+            throw new Error('HTTP client is required for raw query execution');
+        }
+        if (!url) {
+            throw new Error('Server URL is required for raw query execution');
+        }
+
+        try {
+            const queryValue: QueryValue = JSON.parse(queryJson);
+            const request: QueryRequest = {
+                ...queryValue,
+                // Include fieldMap if provided (for server-side field mapping)
+                ...(fieldMap && {fieldMap})
+            };
+
+            const response = await client.post(
+                `${url}/list`,
+                request,
+                {'Content-Type': 'application/json'}
+            );
+
+            return response as QueryResponse;
+        } catch (error) {
+            if (error instanceof SyntaxError) {
+                throw new Error(`Invalid query JSON: ${error.message}`);
+            }
+            throw new Error(`Raw query execution failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+
+    // Execute a query from a JSON object (useful for dynamic queries)
+    static async queryFromJson(
+        queryObject: any,
+        httpClient?: HttpClient,
+        serverUrl?: string
+    ): Promise<QueryResponse> {
+        const client = httpClient || this.httpClient;
+        const url = serverUrl || this.serverUrl;
+
+        if (!client) {
+            throw new Error('HTTP client is required for JSON query execution');
+        }
+        if (!url) {
+            throw new Error('Server URL is required for JSON query execution');
+        }
+
+        try {
+            const request: QueryRequest = queryObject
+
+            const response = await client.post(
+                `${url}/list`,
+                request,
+                {'Content-Type': 'application/json'}
+            );
+
+            return response as QueryResponse;
+        } catch (error) {
+            throw new Error(`JSON query execution failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+
+    // Health check for the server
+    static async healthCheck(httpClient?: HttpClient, serverUrl?: string): Promise<boolean> {
+        const client = httpClient || this.httpClient;
+        const url = serverUrl || this.serverUrl;
+
+        if (!client || !url) {
+            return false;
+        }
+
+        try {
+            await client.post(`${url}/health`, {}, {'Content-Type': 'application/json'});
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    // Get server information
+    static async serverInfo(httpClient?: HttpClient, serverUrl?: string): Promise<any> {
+        const client = httpClient || this.httpClient;
+        const url = serverUrl || this.serverUrl;
+
+        if (!client) {
+            throw new Error('HTTP client is required for server info');
+        }
+        if (!url) {
+            throw new Error('Server URL is required for server info');
+        }
+
+        try {
+            const response = await client.post(
+                `${url}/info`,
+                {},
+                {'Content-Type': 'application/json'}
+            );
+            return response;
+        } catch (error) {
+            throw new Error(`Failed to get server info: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+
+    // Reset SDK configuration
+    static reset(): void {
+        this.httpClient = undefined;
+        this.serverUrl = undefined;
+    }
+
+    // Check if SDK is configured
+    static isConfigured(): boolean {
+        return this.httpClient !== undefined && this.serverUrl !== undefined;
+    }
+
+    // ===== INDEX MANAGEMENT =====
+
+    /**
+     * Create a regular index on a field for query optimization
+     * @param appId - Application ID
+     * @param collection - Collection name
+     * @param fieldName - Field to index
+     * @param options - Optional: store values for fast retrieval
+     */
+    static async createIndex(
+        appId: string,
+        collection: string,
+        fieldName: string,
+        options?: {
+            storeValues?: boolean;
+        }
+    ): Promise<any> {
+        const client = this.httpClient;
+        const url = this.serverUrl;
+
+        if (!client) {
+            throw new Error('HTTP client is required for index creation');
+        }
+        if (!url) {
+            throw new Error('Server URL is required for index creation');
+        }
+
+        const request = {
+            app_id: appId,
+            collection_name: collection,
+            field_name: fieldName,
+            index_config: {
+                index_type: "Secondary",
+                store_values: options?.storeValues !== undefined ? options?.storeValues : true,
+                compression: "None",
+                cache_priority: "Medium",
+                relationship_hints: [],
+                performance_tuning: {
+                    memory_limit_mb: null,
+                    cache_size_entries: null,
+                    prefetch_depth: null,
+                    update_batch_size: null,
+                    background_optimization: true
+                }
+            }
+        };
+
+        const headers: Record<string, string> = {'Content-Type': 'application/json'};
+        if (this.apiKey) {
+            headers['X-API-Key'] = this.apiKey;
+        }
+
+        try {
+            const response = await client.post(
+                `${url}/api/apps/${appId}/collections/${collection}/indexes`,
+                request,
+                headers
+            );
+            return response;
+        } catch (error) {
+            throw new Error(`Index creation failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+
+    /**
+     * Create a unique index on a field (acts as PRIMARY KEY)
+     * Ensures no duplicate values for this field and enables automatic version deduplication
+     * @param appId - Application ID
+     * @param collection - Collection name
+     * @param fieldName - Field to index with unique constraint
+     * @param options - Optional: store values for fast retrieval
+     */
+    static async createUniqueIndex(
+        appId: string,
+        collection: string,
+        fieldName: string,
+        options?: {
+            storeValues?: boolean;
+        }
+    ): Promise<any> {
+        const client = this.httpClient;
+        const url = this.serverUrl;
+
+        if (!client) {
+            throw new Error('HTTP client is required for index creation');
+        }
+        if (!url) {
+            throw new Error('Server URL is required for index creation');
+        }
+
+        const request = {
+            app_id: appId,
+            collection_name: collection,
+            field_name: fieldName,
+            index_config: {
+                index_type: "Primary",  // Primary = unique constraint
+                store_values: options?.storeValues !== undefined ? options?.storeValues : true,
+                compression: "None",
+                cache_priority: "Medium",
+                relationship_hints: [],
+                performance_tuning: {
+                    memory_limit_mb: null,
+                    cache_size_entries: null,
+                    prefetch_depth: null,
+                    update_batch_size: null,
+                    background_optimization: true
+                }
+            }
+        };
+
+        const headers: Record<string, string> = {'Content-Type': 'application/json'};
+        if (this.apiKey) {
+            headers['X-API-Key'] = this.apiKey;
+        }
+
+        try {
+            const response = await client.post(
+                `${url}/api/apps/${appId}/collections/${collection}/indexes`,
+                request,
+                headers
+            );
+            return response;
+        } catch (error) {
+            throw new Error(`Index creation failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+}