|
1 | 1 | # @object-ui/data-objectql |
2 | 2 |
|
3 | | -ObjectQL Data Source Adapter for Object UI - Seamlessly connect your Object UI components with ObjectQL API backends. |
| 3 | +ObjectQL Data Source Adapter for Object UI - Seamlessly connect your Object UI components with ObjectQL API backends using the official **@objectql/sdk**. |
4 | 4 |
|
5 | 5 | ## Features |
6 | 6 |
|
| 7 | +- ✅ **Official SDK Integration** - Built on top of @objectql/sdk for reliable API communication |
7 | 8 | - ✅ **Universal DataSource Interface** - Implements the standard Object UI data source protocol |
8 | 9 | - ✅ **Full TypeScript Support** - Complete type definitions and IntelliSense |
9 | 10 | - ✅ **React Hooks** - Easy-to-use hooks for data fetching and mutations |
10 | 11 | - ✅ **Automatic Query Conversion** - Converts universal query params to ObjectQL format |
11 | 12 | - ✅ **Error Handling** - Robust error handling with typed error responses |
12 | 13 | - ✅ **Authentication** - Built-in support for token-based authentication |
13 | | -- ✅ **Multi-tenant** - Space ID support for multi-tenant environments |
| 14 | +- ✅ **Universal Runtime** - Works in browsers, Node.js, and edge runtimes |
14 | 15 |
|
15 | 16 | ## Installation |
16 | 17 |
|
17 | 18 | ```bash |
18 | 19 | # Using npm |
19 | | -npm install @object-ui/data-objectql |
| 20 | +npm install @object-ui/data-objectql @objectql/sdk |
20 | 21 |
|
21 | 22 | # Using yarn |
22 | | -yarn add @object-ui/data-objectql |
| 23 | +yarn add @object-ui/data-objectql @objectql/sdk |
23 | 24 |
|
24 | 25 | # Using pnpm |
25 | | -pnpm add @object-ui/data-objectql |
| 26 | +pnpm add @object-ui/data-objectql @objectql/sdk |
26 | 27 | ``` |
27 | 28 |
|
| 29 | +**Note**: The package now depends on `@objectql/sdk` and `@objectql/types`, which provide the underlying HTTP client and type definitions. |
| 30 | + |
28 | 31 | ## Quick Start |
29 | 32 |
|
30 | 33 | ### Basic Usage |
@@ -144,15 +147,14 @@ new ObjectQLDataSource(config: ObjectQLConfig) |
144 | 147 | ```typescript |
145 | 148 | interface ObjectQLConfig { |
146 | 149 | baseUrl: string; // ObjectQL API base URL |
147 | | - version?: string; // API version (default: 'v1') |
148 | 150 | token?: string; // Authentication token |
149 | | - spaceId?: string; // Space ID for multi-tenant |
150 | 151 | headers?: Record<string, string>; // Additional headers |
151 | 152 | timeout?: number; // Request timeout (default: 30000ms) |
152 | | - withCredentials?: boolean; // Include credentials (default: true) |
153 | 153 | } |
154 | 154 | ``` |
155 | 155 |
|
| 156 | +**Note**: This configuration is compatible with `@objectql/sdk`'s `DataApiClientConfig`. Additional options supported by the SDK can also be passed. |
| 157 | + |
156 | 158 | #### Methods |
157 | 159 |
|
158 | 160 | ##### find(resource, params) |
@@ -378,6 +380,51 @@ const result = await dataSource.find('contacts'); |
378 | 380 | const contact: Contact = result.data[0]; // Typed! |
379 | 381 | ``` |
380 | 382 |
|
| 383 | +## Architecture |
| 384 | + |
| 385 | +This adapter is built on top of the official ObjectQL SDK: |
| 386 | + |
| 387 | +``` |
| 388 | +Object UI Components |
| 389 | + ↓ |
| 390 | +@object-ui/data-objectql (this package) |
| 391 | + ↓ |
| 392 | +@objectql/sdk (DataApiClient) |
| 393 | + ↓ |
| 394 | +ObjectQL Server API |
| 395 | +``` |
| 396 | + |
| 397 | +### Benefits of Using the Official SDK |
| 398 | + |
| 399 | +- **Reliability**: Uses the official, well-tested ObjectQL HTTP client |
| 400 | +- **Compatibility**: Always compatible with the latest ObjectQL server versions |
| 401 | +- **Type Safety**: Leverages @objectql/types for consistent type definitions |
| 402 | +- **Universal Runtime**: Works in browsers, Node.js, Deno, and edge runtimes |
| 403 | +- **Automatic Updates**: SDK improvements automatically benefit this adapter |
| 404 | + |
| 405 | +## Migration from Previous Versions |
| 406 | + |
| 407 | +If you're upgrading from a previous version that used custom fetch logic: |
| 408 | + |
| 409 | +1. Update your dependencies to include `@objectql/sdk`: |
| 410 | + ```bash |
| 411 | + pnpm add @objectql/sdk @objectql/types |
| 412 | + ``` |
| 413 | + |
| 414 | +2. The configuration interface has been simplified. Remove deprecated options: |
| 415 | + - `version` - The SDK handles API versioning internally |
| 416 | + - `spaceId` - Use custom headers if needed |
| 417 | + - `withCredentials` - The SDK manages this automatically |
| 418 | + |
| 419 | +3. Filter formats now support both object and array notation: |
| 420 | + ```typescript |
| 421 | + // Object format (converted to array internally) |
| 422 | + $filter: { status: 'active', age: 18 } |
| 423 | + |
| 424 | + // Array format (FilterExpression - native ObjectQL format) |
| 425 | + $filter: [['status', '=', 'active'], ['age', '=', 18]] |
| 426 | + ``` |
| 427 | + |
381 | 428 | ## License |
382 | 429 |
|
383 | 430 | MIT |
|
387 | 434 | - [Object UI Documentation](https://www.objectui.org) |
388 | 435 | - [GitHub Repository](https://github.com/objectstack-ai/objectui) |
389 | 436 | - [ObjectQL Documentation](https://www.objectql.com) |
| 437 | +- [ObjectQL SDK](https://github.com/objectstack-ai/objectql) |
0 commit comments