Skip to content

Commit 18428ba

Browse files
hotlonghotlong
committed
添加客户端 SDK 文档，包含安装、使用指南及 API 参考；更新元数据以支持新功能和高级查询选项
1 parent 26afa51 commit 18428ba

File tree

4 files changed

+227
-12
lines changed

4 files changed

+227
-12
lines changed

‎content/docs/references/client-sdk/index.cn.mdx‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
title: 客户端 SDK
3+
description: ObjectStack 官方 TypeScript 客户端
4+
---
5+
6+
# Client SDK
7+
8+
`@objectstack/client-sdk` 是 ObjectStack 的官方 TypeScript 客户端。它提供了一个类型安全、感知协议的接口，用于与 ObjectStack Server 进行交互。
9+
10+
## 核心特性
11+
12+
- **自动发现 (Auto-Discovery)**: 连接到 Server 并自动配置 API 端点路由。
13+
- **类型化元数据**: 获取对象和视图定义，并提供完整的类型支持。
14+
- **统一数据访问**: 为 Schema 中的任何对象提供简单和高级的 CRUD 操作。
15+
16+
## 安装
17+
18+
```bash
19+
pnpm add @objectstack/client-sdk
20+
```
21+
22+
## 使用指南
23+
24+
```typescript
25+
import { ObjectStackClient } from '@objectstack/client-sdk';
26+
27+
// 1. 初始化
28+
const client = new ObjectStackClient({
29+
baseUrl: 'http://localhost:3004', // 你的 ObjectStack Server URL
30+
token: 'optional-auth-token' // (可选) 认证 Token
31+
});
32+
33+
async function main() {
34+
// 2. 连接 (获取服务端系统能力与路由表)
35+
await client.connect();
36+
37+
// 3. 元数据访问
38+
const todoSchema = await client.meta.getObject('todo_task');
39+
console.log('Fields:', todoSchema.fields);
40+
41+
// 4. 高级查询
42+
const tasks = await client.data.find<{ subject: string; priority: number }>('todo_task', {
43+
select: ['subject', 'priority'], // 字段选择
44+
filters: ['priority', '>=', 2], // ObjectStack 过滤器 AST
45+
sort: ['-priority'], // 排序
46+
top: 10
47+
});
48+
49+
// 5. 创建数据
50+
const newTask = await client.data.create('todo_task', {
51+
subject: 'New Task',
52+
priority: 1
53+
});
54+
55+
// 6. 批量操作
56+
await client.data.deleteMany('todo_task', ['id1', 'id2']);
57+
}
58+
```
59+
60+
## API 参考
61+
62+
### 初始化 (Initialization)
63+
```typescript
64+
const client = new ObjectStackClient(config: ClientConfig);
65+
```
66+
- `config.baseUrl`: ObjectStack Server 的地址。
67+
- `config.token`: (可选) Bearer 认证 Token。
68+
- `config.fetch`: (可选) 自定义的 fetch 实现 (例如用于 Next.js 服务端)。
69+
70+
### `client.connect()`
71+
初始化客户端，从 `/api/v1` 获取系统发现清单 (Discovery Manifest)。这将动态映射元数据、数据和 UI 服务的路由。
72+
73+
### `client.meta`
74+
- `getObject(name: string)`: 获取对象 Schema 定义。
75+
- `getView(name: string)`: 获取视图配置 (例如用于自动生成 UI)。
76+
77+
### `client.data`
78+
- `find<T>(object, options)`: 高级查询。
79+
- `get<T>(object, id)`: 根据 ID 获取单条记录。
80+
- `query<T>(object, ast)`: 使用完整 AST 执行复杂查询 (支持 Join, Aggregation 等)。
81+
- `create<T>(object, data)`: 创建记录。
82+
- `createMany<T>(object, data[])`: 批量创建。
83+
- `update<T>(object, id, data)`: 更新记录。
84+
- `updateMany<T>(object, ids[], data)`: 批量更新。
85+
- `delete(object, id)`: 删除记录。
86+
- `deleteMany(object, ids[])`: 批量删除。
87+
88+
### 查询选项 (`QueryOptions`)
89+
`find` 方法接受一个选项对象来控制查询行为：
90+
91+
| 属性 | 类型 | 描述 | 示例 |
92+
| :--- | :--- | :--- | :--- |
93+
| `select` | `string[]` | 返回字段选择 | `['name', 'email']` |
94+
| `filters` | `Map` or `AST` | 过滤条件 | `['status', '=', 'active']` |
95+
| `sort` | `string` or `string[]` | 排序规则 | `['-created_at']` |
96+
| `top` | `number` | 限制返回条数 | `20` |
97+
| `skip` | `number` | 偏移量 (分页) | `0` |

‎content/docs/references/client-sdk/index.mdx‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
title: Client SDK
3+
description: The official TypeScript client for ObjectStack.
4+
---
5+
6+
# Client SDK
7+
8+
The `@objectstack/client-sdk` is the official TypeScript client for ObjectStack. It provides a typed, protocol-aware interface to interact with your ObjectStack Server.
9+
10+
## Features
11+
12+
- **Auto-Discovery**: Connects to your ObjectStack server and automatically configures API endpoints.
13+
- **Typed Metadata**: Retrieve Object and View definitions with full type support.
14+
- **Unified Data Access**: Simple and Advanced CRUD operations for any object in your schema.
15+
16+
## Installation
17+
18+
```bash
19+
pnpm add @objectstack/client-sdk
20+
```
21+
22+
## Usage
23+
24+
```typescript
25+
import { ObjectStackClient } from '@objectstack/client-sdk';
26+
27+
// 1. Initialize
28+
const client = new ObjectStackClient({
29+
baseUrl: 'http://localhost:3004', // Your ObjectStack Server URL
30+
token: 'optional-auth-token'
31+
});
32+
33+
async function main() {
34+
// 2. Connect (Fetches system capabilities)
35+
await client.connect();
36+
37+
// 3. Metadata Access
38+
const todoSchema = await client.meta.getObject('todo_task');
39+
console.log('Fields:', todoSchema.fields);
40+
41+
// 4. Advanced Query
42+
const tasks = await client.data.find<{ subject: string; priority: number }>('todo_task', {
43+
select: ['subject', 'priority'], // Field Selection
44+
filters: ['priority', '>=', 2], // ObjectStack Filter AST
45+
sort: ['-priority'], // Sorting
46+
top: 10
47+
});
48+
49+
// 5. Create Data
50+
const newTask = await client.data.create('todo_task', {
51+
subject: 'New Task',
52+
priority: 1
53+
});
54+
55+
// 6. Batch Operations
56+
await client.data.deleteMany('todo_task', ['id1', 'id2']);
57+
}
58+
```
59+
60+
## API Reference
61+
62+
### Initialization
63+
```typescript
64+
const client = new ObjectStackClient(config: ClientConfig);
65+
```
66+
- `config.baseUrl`: URL of the ObjectStack Server.
67+
- `config.token`: (Optional) Bearer token for authentication.
68+
- `config.fetch`: (Optional) Custom fetch implementation.
69+
70+
### `client.connect()`
71+
Initializes the client by fetching the system discovery manifest from `/api/v1`. This maps dynamic routes for metadata, data, and UI services.
72+
73+
### `client.meta`
74+
- `getObject(name: string)`: Get object schema.
75+
- `getView(name: string)`: Get view configuration (e.g. for automatic UI generation).
76+
77+
### `client.data`
78+
- `find<T>(object, options)`: Advanced query.
79+
- `get<T>(object, id)`: Get single record by ID.
80+
- `query<T>(object, ast)`: Execute complex query using full AST (support for Joins, Aggregations).
81+
- `create<T>(object, data)`: Create record.
82+
- `createMany<T>(object, data[])`: Batch create.
83+
- `update<T>(object, id, data)`: Update record.
84+
- `updateMany<T>(object, ids[], data)`: Batch update.
85+
- `delete(object, id)`: Delete record.
86+
- `deleteMany(object, ids[])`: Batch delete.
87+
88+
### Query Options (`QueryOptions`)
89+
The `find` method accepts an options object to control the query:
90+
91+
| Property | Type | Description | Example |
92+
| :--- | :--- | :--- | :--- |
93+
| `select` | `string[]` | Fields to retrieve | `['name', 'email']` |
94+
| `filters` | `Map` or `AST` | Filtering criteria | `['status', '=', 'active']` |
95+
| `sort` | `string` or `string[]` | Sort order | `['-created_at']` |
96+
| `top` | `number` | Limit records | `20` |
97+
| `skip` | `number` | Offset (Pagination) | `0` |

‎content/docs/references/meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
"data",
66
"ui",
77
"system",
8+
"client-sdk",
89
"ai",
910
"misc"
1011
]

‎packages/client-sdk/README.md‎

Lines changed: 32 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,8 @@ import { ObjectStackClient } from '@objectstack/client-sdk';
2121

2222
// 1. Initialize
2323
const client = new ObjectStackClient({
24-
baseUrl: 'http://localhost:3004' // Your ObjectStack Server URL
24+
baseUrl: 'http://localhost:3004', // Your ObjectStack Server URL
25+
token: 'optional-auth-token'
2526
});
2627

2728
async function main() {
@@ -32,16 +33,22 @@ async function main() {
3233
const todoSchema = await client.meta.getObject('todo_task');
3334
console.log('Fields:', todoSchema.fields);
3435

35-
// 4. Data Access
36-
const tasks = await client.data.find('todo_task', {
37-
status: 'pending' // Simple filtering
36+
// 4. Advanced Query
37+
const tasks = await client.data.find<{ subject: string; priority: number }>('todo_task', {
38+
select: ['subject', 'priority'], // Field Selection
39+
filters: ['priority', '>=', 2], // ObjectStack Filter AST
40+
sort: ['-priority'], // Sorting
41+
top: 10
3842
});
3943

4044
// 5. Create Data
41-
await client.data.create('todo_task', {
42-
title: 'New Task',
43-
status: 'todo'
45+
const newTask = await client.data.create('todo_task', {
46+
subject: 'New Task',
47+
priority: 1
4448
});
49+
50+
// 6. Batch Operations
51+
await client.data.deleteMany('todo_task', ['id1', 'id2']);
4552
}
4653
```
4754

@@ -55,8 +62,21 @@ Initializes the client by fetching the system discovery manifest from `/api/v1`.
5562
- `getView(name: string)`: Get view configuration.
5663

5764
### `client.data`
58-
- `find(object: string, query?: Record<string, any>)`: List records.
59-
- `get(object: string, id: string)`: Get single record.
60-
- `create(object: string, data: any)`: Create record.
61-
- `update(object: string, id: string, data: any)`: Update record.
62-
- `delete(object: string, id: string)`: Delete record.
65+
- `find<T>(object, options)`: Advanced query with filtering, sorting, selection.
66+
- `get<T>(object, id)`: Get single record by ID.
67+
- `query<T>(object, ast)`: Execute complex query using full AST.
68+
- `create<T>(object, data)`: Create record.
69+
- `createMany<T>(object, data[])`: Batch create records.
70+
- `update<T>(object, id, data)`: Update record.
71+
- `updateMany<T>(object, ids[], data)`: Batch update records.
72+
- `delete(object, id)`: Delete record.
73+
- `deleteMany(object, ids[])`: Batch delete records.
74+
75+
### Query Options
76+
The `find` method accepts an options object:
77+
- `select`: Array of field names to retrieve.
78+
- `filters`: Simple key-value map OR Filter AST `['field', 'op', 'value']`.
79+
- `sort`: Sort string (`'name'`) or array `['-created_at', 'name']`.
80+
- `top`: Limit number of records.
81+
- `skip`: Offset for pagination.
82+

0 commit comments

Comments
 (0)