Skip to content

Commit aa2fe6d

Browse files
Copilothuangyiirene
Copilot
and
huangyiirene
committed
Add index pages for /data-access and /server in apps/site documentation
Co-authored-by: huangyiirene <7665279+huangyiirene@users.noreply.github.com>
1 parent 565ce1a commit aa2fe6d

File tree

2 files changed

+246
-0
lines changed

2 files changed

+246
-0
lines changed

‎apps/site/content/docs/data-access/index.mdx‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
title: Data Access
3+
description: Learn how to query and access data using ObjectQL's type-safe SDK and JSON-based protocol
4+
---
5+
6+
ObjectQL provides powerful data access capabilities through a **JSON-based Protocol** that works seamlessly across different database backends. Unlike SQL strings or Query Builders, ObjectQL queries are structured data that are type-safe, serializable, and perfect for AI agents.
7+
8+
## Overview
9+
10+
The data access layer in ObjectQL is designed to be:
11+
12+
- **Type-Safe**: Full TypeScript support with auto-generated types from your schema
13+
- **Database Agnostic**: The same query works on MongoDB, PostgreSQL, SQLite, and more
14+
- **AI-Friendly**: Structured JSON format prevents hallucinations and syntax errors
15+
- **Serializable**: Queries can be sent over HTTP, stored in files, or logged for debugging
16+
17+
## Key Topics
18+
19+
### [Querying Data](/docs/data-access/querying)
20+
21+
Learn the fundamentals of querying data with ObjectQL:
22+
- Find operations and filters
23+
- Sorting and pagination
24+
- Field selection and data expansion
25+
- Aggregations and grouping
26+
- Complex queries with nested conditions
27+
28+
### [Client SDK](/docs/data-access/sdk)
29+
30+
Use the TypeScript SDK for type-safe data access:
31+
- Installation and setup
32+
- Basic CRUD operations
33+
- Advanced querying techniques
34+
- Error handling
35+
- TypeScript integration
36+
37+
### [Query Best Practices](/docs/data-access/best-practices)
38+
39+
Optimize your queries for performance:
40+
- Query optimization strategies
41+
- Avoiding N+1 problems
42+
- Efficient data loading
43+
- Caching strategies
44+
- Performance benchmarks
45+
46+
## Quick Example
47+
48+
```typescript
49+
import { ObjectQL } from '@objectql/core';
50+
51+
// Initialize ObjectQL
52+
const app = new ObjectQL({
53+
datasources: {
54+
default: driver
55+
}
56+
});
57+
58+
await app.init();
59+
const ctx = app.createContext({ isSystem: true });
60+
61+
// Query data with filters
62+
const products = await ctx.object('product').find({
63+
fields: ['name', 'price', 'category'],
64+
filters: [
65+
['category', '=', 'electronics'],
66+
'and',
67+
['price', '<', 1000]
68+
],
69+
sort: [['price', 'asc']],
70+
top: 10
71+
});
72+
73+
console.log('Products:', products);
74+
```
75+
76+
## JSON Query Protocol
77+
78+
All queries in ObjectQL follow a consistent JSON structure:
79+
80+
```json
81+
{
82+
"op": "find",
83+
"object": "product",
84+
"args": {
85+
"fields": ["name", "price"],
86+
"filters": [["category", "=", "electronics"]],
87+
"top": 10
88+
}
89+
}
90+
```
91+
92+
This structure makes it easy for frontends, AI agents, and external systems to generate safe, valid queries.
93+
94+
## Next Steps
95+
96+
- Start with **[Querying Data](/docs/data-access/querying)** to learn the basics
97+
- Explore the **[Client SDK](/docs/data-access/sdk)** for type-safe access
98+
- Review **[Best Practices](/docs/data-access/best-practices)** for optimization strategies
99+
- Check the **[API Reference](/docs/reference/api)** for complete documentation

‎apps/site/content/docs/server/index.mdx‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
title: Server & Deployment
3+
description: Learn how to configure, integrate, and deploy ObjectQL applications
4+
---
5+
6+
ObjectQL is designed to be **framework-agnostic** and can be integrated with any Node.js server or deployed to various environments. This section covers server configuration, integration patterns, and deployment strategies.
7+
8+
## Overview
9+
10+
The server layer in ObjectQL provides:
11+
12+
- **Multiple Framework Support**: Express, Next.js, Fastify, and more
13+
- **API Styles**: REST, JSON-RPC, GraphQL, and WebSocket support
14+
- **Configuration Management**: Environment-based configuration
15+
- **Plugin System**: Extend functionality with plugins
16+
- **Microservices**: Federation and distributed architectures
17+
18+
## Key Topics
19+
20+
### [Configuration](/docs/server/configuration)
21+
22+
Configure your ObjectQL application:
23+
- Database connections
24+
- Environment variables
25+
- Metadata loading
26+
- Driver configuration
27+
- Runtime options
28+
29+
### [Server Integration](/docs/server/integration)
30+
31+
Integrate ObjectQL with web frameworks:
32+
- Express.js setup
33+
- Next.js integration
34+
- Fastify adapter
35+
- Custom server setup
36+
- HTTP API exposure
37+
38+
### [Microservices & Federation](/docs/server/microservices)
39+
40+
Build distributed systems with ObjectQL:
41+
- Service federation
42+
- Remote data sources
43+
- Cross-service queries
44+
- Load balancing
45+
- Service discovery
46+
47+
### [Plugin System](/docs/server/plugins)
48+
49+
Extend ObjectQL with plugins:
50+
- Creating custom plugins
51+
- Plugin lifecycle
52+
- Bundling behavior
53+
- Sharing plugins
54+
- Official plugins
55+
56+
## Quick Setup
57+
58+
### Express Integration
59+
60+
```typescript
61+
import express from 'express';
62+
import { ObjectQL } from '@objectql/core';
63+
import { SqlDriver } from '@objectql/driver-sql';
64+
import { createNodeHandler } from '@objectql/server';
65+
66+
const app = express();
67+
68+
// Initialize ObjectQL
69+
const objectql = new ObjectQL({
70+
datasources: {
71+
default: new SqlDriver({
72+
client: 'postgresql',
73+
connection: process.env.DATABASE_URL
74+
})
75+
}
76+
});
77+
78+
await objectql.init();
79+
80+
// Mount ObjectQL handler
81+
app.use('/api/objectql', createNodeHandler(objectql));
82+
83+
// Start server
84+
app.listen(3000, () => {
85+
console.log('Server running on http://localhost:3000');
86+
});
87+
```
88+
89+
### Configuration File
90+
91+
```typescript
92+
// objectql.config.ts
93+
import { defineConfig } from '@objectql/core';
94+
95+
export default defineConfig({
96+
datasources: {
97+
default: {
98+
driver: 'sql',
99+
client: 'postgresql',
100+
connection: {
101+
host: process.env.DB_HOST,
102+
database: process.env.DB_NAME,
103+
user: process.env.DB_USER,
104+
password: process.env.DB_PASSWORD
105+
}
106+
}
107+
},
108+
modules: [
109+
'src/objects',
110+
'@objectql/module-auth'
111+
]
112+
});
113+
```
114+
115+
## Deployment Patterns
116+
117+
### Traditional Server
118+
119+
Deploy to VPS, EC2, or dedicated servers:
120+
- Process management with PM2
121+
- Nginx reverse proxy
122+
- Environment configuration
123+
- Database migrations
124+
125+
### Serverless
126+
127+
Deploy to serverless platforms:
128+
- AWS Lambda
129+
- Vercel Functions
130+
- Cloudflare Workers
131+
- Database connection pooling
132+
133+
### Containers
134+
135+
Deploy with Docker:
136+
- Dockerfile configuration
137+
- Docker Compose setup
138+
- Kubernetes deployment
139+
- Health checks and monitoring
140+
141+
## Next Steps
142+
143+
- Configure your application with **[Configuration](/docs/server/configuration)**
144+
- Integrate with your framework using **[Server Integration](/docs/server/integration)**
145+
- Scale with **[Microservices](/docs/server/microservices)**
146+
- Extend with the **[Plugin System](/docs/server/plugins)**
147+
- Review **[API Reference](/docs/reference/api)** for complete documentation

0 commit comments

Comments
 (0)