@0xobelisk/grpc-client 1.2.0-pre.68

package/LICENSE

@@ -0,0 +1,92 @@
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             Obelisk Labs
+
+Licensed Work:        Dubhe
+                      The Licensed Work is (c) 2023 Obelisk Labs
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License’s text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+-----------------------------------------------------------------------------
+
+Covenants of Licensor
+
+In consideration of the right to use this License’s text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.

package/README.md

@@ -0,0 +1,407 @@
+# @0xobelisk/grpc-client
+
+TypeScript gRPC client for interacting with the Dubhe Indexer using protobuf-ts.
+
+## Features
+
+- 🔍 **Advanced Querying**: Query table data with comprehensive filtering, sorting, and pagination
+- 📡 **Real-time Subscription**: Subscribe to table updates and receive real-time data changes
+- 🛠️ **Flexible API**: Both simple and advanced query APIs with fluent query builder
+- 🔧 **Type-Safe**: Full TypeScript support with generated protobuf types
+- 📊 **Rich Filtering**: Support for various filter operators (equals, like, in, between, etc.)
+- 📄 **Pagination**: Built-in pagination support with page-based navigation
+- 🛠️ **Utility Functions**: Rich utility functions for data processing and filtering
+- 🌐 **Web Compatible**: Uses gRPC-Web transport for browser compatibility
+
+## Installation
+
+```bash
+npm install @0xobelisk/grpc-client
+```
+
+## Quick Start
+
+### Basic Connection
+
+```typescript
+import { createDubheGrpcClient } from '@0xobelisk/grpc-client';
+
+const client = createDubheGrpcClient({
+  endpoint: '127.0.0.1:8080', // gRPC server endpoint (without http://)
+  timeout: 10000,
+  enableRetry: true,
+  retryAttempts: 3
+});
+
+await client.connect();
+console.log('Connected successfully!');
+```
+
+### Simple Querying
+
+```typescript
+// Basic query - get all data with pagination
+const response = await client.query('users', {
+  pageSize: 10,
+  includeTotalCount: true
+});
+
+// Query with field selection
+const response = await client.query('users', {
+  select: ['id', 'name', 'email'],
+  pageSize: 20
+});
+
+// Query with filtering
+const response = await client.query('users', {
+  where: {
+    status: 'active',
+    role: ['admin', 'user'], // IN operator
+    age: { min: 18, max: 65 } // BETWEEN operator
+  },
+  orderBy: [
+    { field: 'created_at', direction: 'desc' },
+    { field: 'name', direction: 'asc' }
+  ],
+  page: 1,
+  pageSize: 20,
+  includeTotalCount: true
+});
+```
+
+### Advanced Querying
+
+```typescript
+import { FilterOperator, SortDirection } from '@0xobelisk/grpc-client';
+
+const response = await client.queryTable({
+  tableName: 'users',
+  selectFields: ['id', 'name', 'created_at'],
+  filters: [
+    {
+      fieldName: 'name',
+      operator: FilterOperator.LIKE,
+      value: { stringValue: '%john%' }
+    },
+    {
+      fieldName: 'age',
+      operator: FilterOperator.GREATER_THAN,
+      value: { intValue: 18 }
+    },
+    {
+      fieldName: 'status',
+      operator: FilterOperator.IN,
+      value: { stringList: { values: ['active', 'pending'] } }
+    }
+  ],
+  sorts: [
+    {
+      fieldName: 'created_at',
+      direction: SortDirection.DESCENDING,
+      priority: 0
+    }
+  ],
+  pagination: {
+    page: 1,
+    pageSize: 10
+  },
+  includeTotalCount: true
+});
+```
+
+### Query Builder (Fluent API)
+
+```typescript
+const response = await client
+  .createQueryBuilder()
+  .tableName('users')
+  .select('id', 'name', 'email')
+  .where({
+    status: 'active',
+    role: ['admin', 'user']
+  })
+  .orderBy('created_at', 'desc')
+  .page(1, 15)
+  .includeTotalCount(true)
+  .execute();
+```
+
+### Real-time Subscriptions
+
+```typescript
+const subscriptionId = client.subscribeTable(
+  ['users', 'posts'], // table names to subscribe to
+  {
+    onUpdate: (change) => {
+      console.log(`Table updated: ${change.table_id}`);
+      console.log('New data:', change.data);
+    },
+    onError: (error) => {
+      console.error('Subscription error:', error);
+    },
+    onConnect: () => {
+      console.log('Subscription connected');
+    },
+    onDisconnect: () => {
+      console.log('Subscription disconnected');
+    }
+  }
+);
+
+console.log(`Subscription ID: ${subscriptionId}`);
+
+// Later, unsubscribe
+client.unsubscribe(subscriptionId);
+```
+
+## Configuration
+
+```typescript
+interface DubheGrpcClientConfig {
+  endpoint: string; // gRPC server endpoint
+  enableRetry?: boolean; // Enable automatic retry (default: true)
+  retryAttempts?: number; // Number of retry attempts (default: 3)
+  timeout?: number; // Request timeout in ms (default: 30000)
+}
+```
+
+## Filter Operators
+
+The client supports various filter operators:
+
+```typescript
+import { FilterOperator } from '@0xobelisk/grpc-client';
+
+// Available operators:
+FilterOperator.EQUALS;
+FilterOperator.NOT_EQUALS;
+FilterOperator.GREATER_THAN;
+FilterOperator.GREATER_THAN_EQUAL;
+FilterOperator.LESS_THAN;
+FilterOperator.LESS_THAN_EQUAL;
+FilterOperator.LIKE;
+FilterOperator.NOT_LIKE;
+FilterOperator.IN;
+FilterOperator.NOT_IN;
+FilterOperator.IS_NULL;
+FilterOperator.IS_NOT_NULL;
+FilterOperator.BETWEEN;
+FilterOperator.NOT_BETWEEN;
+```
+
+## Utility Functions
+
+### GrpcUtils
+
+```typescript
+import { GrpcUtils } from '@0xobelisk/grpc-client';
+
+// Extract field from data
+const value = GrpcUtils.extractField(data, 'fieldName');
+
+// Convert protobuf struct to object
+const obj = GrpcUtils.structToObject(struct);
+
+// Check if error is gRPC error
+if (GrpcUtils.isGrpcError(error, 404)) {
+  console.log('Not found error');
+}
+
+// Format error for display
+const message = GrpcUtils.formatGrpcError(error);
+```
+
+### Data Processing Utilities
+
+```typescript
+import { DataUtils, QueryUtils, ValidationUtils } from '@0xobelisk/grpc-client';
+
+// Build filters easily
+const filters = [
+  QueryUtils.equals('status', 'active'),
+  QueryUtils.in('role', ['admin', 'user']),
+  QueryUtils.like('name', '%john%'),
+  QueryUtils.between('age', 18, 65),
+  QueryUtils.isNotNull('email')
+];
+
+// Data manipulation
+const flattened = DataUtils.flatten(nestedObject);
+const merged = DataUtils.deepMerge(obj1, obj2);
+const picked = DataUtils.pick(object, ['field1', 'field2']);
+
+// Validation
+const isValid = ValidationUtils.isValidTableName('users');
+const isValidField = ValidationUtils.isValidFieldName('user.name');
+```
+
+## Error Handling
+
+```typescript
+import { ErrorUtils } from '@0xobelisk/grpc-client';
+
+try {
+  const response = await client.query('users');
+} catch (error) {
+  if (ErrorUtils.isTimeoutError(error)) {
+    console.log('Request timed out');
+  } else if (ErrorUtils.isConnectionError(error)) {
+    console.log('Connection failed');
+  } else {
+    console.log('Other error:', ErrorUtils.formatError(error));
+  }
+}
+```
+
+## Connection Management
+
+```typescript
+// Check connection status
+console.log('Status:', client.getStatus()); // 'connected', 'connecting', 'disconnected', 'error'
+
+// Check if connected
+if (client.isConnected()) {
+  console.log('Client is ready');
+}
+
+// Get active subscriptions
+console.log('Active subscriptions:', client.getActiveSubscriptionCount());
+console.log('Subscription IDs:', client.getActiveSubscriptionIds());
+
+// Disconnect
+client.disconnect();
+```
+
+## Complete Example
+
+```typescript
+import {
+  createDubheGrpcClient,
+  FilterOperator,
+  SortDirection,
+  GrpcUtils
+} from '@0xobelisk/grpc-client';
+
+async function example() {
+  // Create and connect client
+  const client = createDubheGrpcClient({
+    endpoint: '127.0.0.1:8080',
+    timeout: 10000
+  });
+
+  await client.connect();
+
+  try {
+    // Query data
+    const users = await client.query('users', {
+      where: { status: 'active' },
+      orderBy: [{ field: 'created_at', direction: 'desc' }],
+      pageSize: 10,
+      includeTotalCount: true
+    });
+
+    console.log(`Found ${users.totalCount} users`);
+    console.log('Users:', users.data);
+
+    // Subscribe to updates
+    const subscriptionId = client.subscribeTable(['users'], {
+      onUpdate: (change) => {
+        console.log('User updated:', change.data);
+      },
+      onError: (error) => {
+        console.error('Subscription error:', GrpcUtils.formatGrpcError(error));
+      }
+    });
+
+    // Cleanup on exit
+    process.on('SIGINT', () => {
+      client.unsubscribe(subscriptionId);
+      client.disconnect();
+      process.exit(0);
+    });
+  } catch (error) {
+    console.error('Query failed:', GrpcUtils.formatGrpcError(error));
+  }
+}
+
+example();
+```
+
+## Advanced Types
+
+For advanced usage, you can access the raw protobuf types:
+
+```typescript
+import {
+  ProtoDubheGrpcClient,
+  ProtoQueryRequest,
+  ProtoQueryResponse
+} from '@0xobelisk/grpc-client';
+
+// Direct access to protobuf client if needed
+const protoClient = new ProtoDubheGrpcClient(transport);
+```
+
+## Development
+
+### Generate Protobuf Types
+
+```bash
+npm run generate
+```
+
+This command will:
+
+1. Clean existing proto files
+2. Generate new TypeScript types from `.proto` files
+3. Format the generated code
+
+### Build
+
+```bash
+npm run build
+```
+
+### Lint
+
+```bash
+npm run lint
+npm run lint:fix
+```
+
+## Migration from v1.x
+
+The v2.x version introduces several breaking changes:
+
+1. **Removed EventEmitter**: Client no longer extends EventEmitter for simpler API
+2. **Updated Transport**: Now uses `@protobuf-ts/grpcweb-transport` instead of `@grpc/grpc-js`
+3. **Type-safe**: Full TypeScript support with generated protobuf types
+4. **Simplified API**: Cleaner method signatures and better error handling
+
+### Before (v1.x)
+
+```typescript
+client.on('connect', () => console.log('Connected'));
+client.on('error', (error) => console.error(error));
+```
+
+### After (v2.x)
+
+```typescript
+// Connection status is handled through method calls
+await client.connect();
+if (client.isConnected()) {
+  console.log('Connected');
+}
+
+// Error handling through try-catch
+try {
+  await client.query('table');
+} catch (error) {
+  console.error(error);
+}
+```
+
+## License
+
+Apache-2.0

package/dist/client.d.ts

@@ -0,0 +1,6 @@
+import type { GrpcWebOptions } from '@protobuf-ts/grpcweb-transport';
+import { DubheGrpcClient as ProtoDubheGrpcClient } from './proto/dubhe_grpc.client';
+export declare class DubheGrpcClient {
+    dubheGrpcClient: ProtoDubheGrpcClient;
+    constructor(options: GrpcWebOptions);
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export { DubheGrpcClient as ProtoDubheGrpcClient } from './proto/dubhe_grpc.client';
+export { FilterOperator, SortDirection } from './proto/dubhe_grpc';
+export type { QueryRequest, QueryResponse, SubscribeRequest, TableChange, FilterCondition, FilterValue, SortSpecification, PaginationRequest, PaginationResponse } from './proto/dubhe_grpc';
+export { DubheGrpcClient } from './client';