Skip to content

Commit f837385

Browse files
Copilothotlong
Copilot
and
hotlong
committed
Add comprehensive GraphQL protocol schemas and security features
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent 055ac42 commit f837385

21 files changed

Lines changed: 5299 additions & 0 deletions

‎content/docs/references/api/graphql.mdx‎

Lines changed: 275 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,275 @@
1+
---
2+
title: Graphql
3+
description: Graphql protocol schemas
4+
---
5+
6+
# Graphql
7+
8+
<Callout type="info">
9+
**Source:** `packages/spec/src/api/graphql.zod.ts`
10+
</Callout>
11+
12+
## TypeScript Usage
13+
14+
```typescript
15+
import { FieldTypeToGraphQLMappingSchema, GraphQLConfigSchema, GraphQLDataLoaderConfigSchema, GraphQLDirectiveConfigSchema, GraphQLDirectiveLocationSchema, GraphQLMutationConfigSchema, GraphQLPersistedQuerySchema, GraphQLQueryComplexitySchema, GraphQLQueryConfigSchema, GraphQLQueryDepthLimitSchema, GraphQLRateLimitSchema, GraphQLResolverConfigSchema, GraphQLScalarTypeSchema, GraphQLSubscriptionConfigSchema, GraphQLTypeConfigSchema } from '@objectstack/spec/api';
16+
import type { FieldTypeToGraphQLMapping, GraphQLConfig, GraphQLDataLoaderConfig, GraphQLDirectiveConfig, GraphQLDirectiveLocation, GraphQLMutationConfig, GraphQLPersistedQuery, GraphQLQueryComplexity, GraphQLQueryConfig, GraphQLQueryDepthLimit, GraphQLRateLimit, GraphQLResolverConfig, GraphQLScalarType, GraphQLSubscriptionConfig, GraphQLTypeConfig } from '@objectstack/spec/api';
17+
18+
// Validate data
19+
const result = FieldTypeToGraphQLMappingSchema.parse(data);
20+
```
21+
22+
---
23+
24+
## FieldTypeToGraphQLMapping
25+
26+
Field type to GraphQL type mapping configuration
27+
28+
---
29+
30+
## GraphQLConfig
31+
32+
### Properties
33+
34+
| Property | Type | Required | Description |
35+
| :--- | :--- | :--- | :--- |
36+
| **enabled** | `boolean` | optional | Enable GraphQL API |
37+
| **path** | `string` | optional | GraphQL endpoint path |
38+
| **playground** | `object` | optional | GraphQL Playground configuration |
39+
| **schema** | `object` | optional | Schema generation configuration |
40+
| **dataLoaders** | `object[]` | optional | DataLoader configurations |
41+
| **security** | `object` | optional | Security configuration |
42+
43+
---
44+
45+
## GraphQLDataLoaderConfig
46+
47+
### Properties
48+
49+
| Property | Type | Required | Description |
50+
| :--- | :--- | :--- | :--- |
51+
| **name** | `string` | ✅ | DataLoader name |
52+
| **source** | `string` | ✅ | Source object or datasource |
53+
| **batchFunction** | `object` | ✅ | Batch function configuration |
54+
| **cache** | `object` | optional | DataLoader caching |
55+
| **options** | `object` | optional | DataLoader options |
56+
57+
---
58+
59+
## GraphQLDirectiveConfig
60+
61+
### Properties
62+
63+
| Property | Type | Required | Description |
64+
| :--- | :--- | :--- | :--- |
65+
| **name** | `string` | ✅ | Directive name (camelCase) |
66+
| **description** | `string` | optional | Directive description |
67+
| **locations** | `Enum<'QUERY' \| 'MUTATION' \| 'SUBSCRIPTION' \| 'FIELD' \| 'FRAGMENT_DEFINITION' \| 'FRAGMENT_SPREAD' \| 'INLINE_FRAGMENT' \| 'VARIABLE_DEFINITION' \| 'SCHEMA' \| 'SCALAR' \| 'OBJECT' \| 'FIELD_DEFINITION' \| 'ARGUMENT_DEFINITION' \| 'INTERFACE' \| 'UNION' \| 'ENUM' \| 'ENUM_VALUE' \| 'INPUT_OBJECT' \| 'INPUT_FIELD_DEFINITION'>[]` | ✅ | Directive locations |
68+
| **args** | `Record<string, object>` | optional | Directive arguments |
69+
| **repeatable** | `boolean` | optional | Can be applied multiple times |
70+
| **implementation** | `object` | optional | Directive implementation |
71+
72+
---
73+
74+
## GraphQLDirectiveLocation
75+
76+
### Allowed Values
77+
78+
* `QUERY`
79+
* `MUTATION`
80+
* `SUBSCRIPTION`
81+
* `FIELD`
82+
* `FRAGMENT_DEFINITION`
83+
* `FRAGMENT_SPREAD`
84+
* `INLINE_FRAGMENT`
85+
* `VARIABLE_DEFINITION`
86+
* `SCHEMA`
87+
* `SCALAR`
88+
* `OBJECT`
89+
* `FIELD_DEFINITION`
90+
* `ARGUMENT_DEFINITION`
91+
* `INTERFACE`
92+
* `UNION`
93+
* `ENUM`
94+
* `ENUM_VALUE`
95+
* `INPUT_OBJECT`
96+
* `INPUT_FIELD_DEFINITION`
97+
98+
---
99+
100+
## GraphQLMutationConfig
101+
102+
### Properties
103+
104+
| Property | Type | Required | Description |
105+
| :--- | :--- | :--- | :--- |
106+
| **name** | `string` | ✅ | Mutation field name (camelCase recommended) |
107+
| **object** | `string` | ✅ | Source ObjectQL object name |
108+
| **type** | `Enum<'create' \| 'update' \| 'delete' \| 'upsert' \| 'custom'>` | ✅ | Mutation type |
109+
| **description** | `string` | optional | Mutation description |
110+
| **input** | `object` | optional | Input configuration |
111+
| **output** | `object` | optional | Output configuration |
112+
| **transaction** | `object` | optional | Transaction configuration |
113+
| **authRequired** | `boolean` | optional | Require authentication |
114+
| **permissions** | `string[]` | optional | Required permissions |
115+
| **hooks** | `object` | optional | Lifecycle hooks |
116+
117+
---
118+
119+
## GraphQLPersistedQuery
120+
121+
### Properties
122+
123+
| Property | Type | Required | Description |
124+
| :--- | :--- | :--- | :--- |
125+
| **enabled** | `boolean` | optional | Enable persisted queries |
126+
| **mode** | `Enum<'optional' \| 'required'>` | optional | Persisted query mode (optional: allow both, required: only persisted) |
127+
| **store** | `object` | optional | Query store configuration |
128+
| **apq** | `object` | optional | Automatic Persisted Queries configuration |
129+
| **allowlist** | `object` | optional | Query allowlist configuration |
130+
| **security** | `object` | optional | Security configuration |
131+
132+
---
133+
134+
## GraphQLQueryComplexity
135+
136+
### Properties
137+
138+
| Property | Type | Required | Description |
139+
| :--- | :--- | :--- | :--- |
140+
| **enabled** | `boolean` | optional | Enable query complexity limiting |
141+
| **maxComplexity** | `integer` | optional | Maximum query complexity |
142+
| **defaultFieldComplexity** | `integer` | optional | Default complexity per field |
143+
| **fieldComplexity** | `Record<string, integer \| object>` | optional | Per-field complexity configuration |
144+
| **listMultiplier** | `number` | optional | Multiplier for list fields |
145+
| **onComplexityExceeded** | `Enum<'reject' \| 'log' \| 'warn'>` | optional | Action when complexity exceeded |
146+
| **errorMessage** | `string` | optional | Custom error message for complexity violations |
147+
148+
---
149+
150+
## GraphQLQueryConfig
151+
152+
### Properties
153+
154+
| Property | Type | Required | Description |
155+
| :--- | :--- | :--- | :--- |
156+
| **name** | `string` | ✅ | Query field name (camelCase recommended) |
157+
| **object** | `string` | ✅ | Source ObjectQL object name |
158+
| **type** | `Enum<'get' \| 'list' \| 'search'>` | ✅ | Query type |
159+
| **description** | `string` | optional | Query description |
160+
| **args** | `Record<string, object>` | optional | Query arguments |
161+
| **filtering** | `object` | optional | Filtering capabilities |
162+
| **sorting** | `object` | optional | Sorting capabilities |
163+
| **pagination** | `object` | optional | Pagination configuration |
164+
| **fields** | `object` | optional | Field selection configuration |
165+
| **authRequired** | `boolean` | optional | Require authentication |
166+
| **permissions** | `string[]` | optional | Required permissions |
167+
| **cache** | `object` | optional | Query caching |
168+
169+
---
170+
171+
## GraphQLQueryDepthLimit
172+
173+
### Properties
174+
175+
| Property | Type | Required | Description |
176+
| :--- | :--- | :--- | :--- |
177+
| **enabled** | `boolean` | optional | Enable query depth limiting |
178+
| **maxDepth** | `integer` | optional | Maximum query depth |
179+
| **ignoreFields** | `string[]` | optional | Fields excluded from depth calculation |
180+
| **onDepthExceeded** | `Enum<'reject' \| 'log' \| 'warn'>` | optional | Action when depth exceeded |
181+
| **errorMessage** | `string` | optional | Custom error message for depth violations |
182+
183+
---
184+
185+
## GraphQLRateLimit
186+
187+
### Properties
188+
189+
| Property | Type | Required | Description |
190+
| :--- | :--- | :--- | :--- |
191+
| **enabled** | `boolean` | optional | Enable rate limiting |
192+
| **strategy** | `Enum<'token_bucket' \| 'fixed_window' \| 'sliding_window' \| 'cost_based'>` | optional | Rate limiting strategy |
193+
| **global** | `object` | optional | Global rate limits |
194+
| **perUser** | `object` | optional | Per-user rate limits |
195+
| **costBased** | `object` | optional | Cost-based rate limiting |
196+
| **operations** | `Record<string, object>` | optional | Per-operation rate limits |
197+
| **onLimitExceeded** | `Enum<'reject' \| 'queue' \| 'log'>` | optional | Action when rate limit exceeded |
198+
| **errorMessage** | `string` | optional | Custom error message for rate limit violations |
199+
| **includeHeaders** | `boolean` | optional | Include rate limit headers in response |
200+
201+
---
202+
203+
## GraphQLResolverConfig
204+
205+
### Properties
206+
207+
| Property | Type | Required | Description |
208+
| :--- | :--- | :--- | :--- |
209+
| **path** | `string` | ✅ | Resolver path (Type.field) |
210+
| **type** | `Enum<'datasource' \| 'computed' \| 'script' \| 'proxy'>` | ✅ | Resolver implementation type |
211+
| **implementation** | `object` | optional | Implementation configuration |
212+
| **cache** | `object` | optional | Resolver caching |
213+
214+
---
215+
216+
## GraphQLScalarType
217+
218+
### Allowed Values
219+
220+
* `ID`
221+
* `String`
222+
* `Int`
223+
* `Float`
224+
* `Boolean`
225+
* `DateTime`
226+
* `Date`
227+
* `Time`
228+
* `JSON`
229+
* `JSONObject`
230+
* `Upload`
231+
* `URL`
232+
* `Email`
233+
* `PhoneNumber`
234+
* `Currency`
235+
* `Decimal`
236+
* `BigInt`
237+
* `Long`
238+
* `UUID`
239+
* `Base64`
240+
* `Void`
241+
242+
---
243+
244+
## GraphQLSubscriptionConfig
245+
246+
### Properties
247+
248+
| Property | Type | Required | Description |
249+
| :--- | :--- | :--- | :--- |
250+
| **name** | `string` | ✅ | Subscription field name (camelCase recommended) |
251+
| **object** | `string` | ✅ | Source ObjectQL object name |
252+
| **events** | `Enum<'created' \| 'updated' \| 'deleted' \| 'custom'>[]` | ✅ | Events to subscribe to |
253+
| **description** | `string` | optional | Subscription description |
254+
| **filter** | `object` | optional | Subscription filtering |
255+
| **payload** | `object` | optional | Payload configuration |
256+
| **authRequired** | `boolean` | optional | Require authentication |
257+
| **permissions** | `string[]` | optional | Required permissions |
258+
| **rateLimit** | `object` | optional | Subscription rate limiting |
259+
260+
---
261+
262+
## GraphQLTypeConfig
263+
264+
### Properties
265+
266+
| Property | Type | Required | Description |
267+
| :--- | :--- | :--- | :--- |
268+
| **name** | `string` | ✅ | GraphQL type name (PascalCase recommended) |
269+
| **object** | `string` | ✅ | Source ObjectQL object name |
270+
| **description** | `string` | optional | Type description |
271+
| **fields** | `object` | optional | Field configuration |
272+
| **interfaces** | `string[]` | optional | GraphQL interface names |
273+
| **isInterface** | `boolean` | optional | Define as GraphQL interface |
274+
| **directives** | `object[]` | optional | GraphQL directives |
275+

‎content/docs/references/api/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ This section contains all protocol schemas for the api layer of ObjectStack.
1111
<Card href="./contract" title="Contract" description="Source: packages/spec/src/api/contract.zod.ts" />
1212
<Card href="./discovery" title="Discovery" description="Source: packages/spec/src/api/discovery.zod.ts" />
1313
<Card href="./endpoint" title="Endpoint" description="Source: packages/spec/src/api/endpoint.zod.ts" />
14+
<Card href="./graphql" title="Graphql" description="Source: packages/spec/src/api/graphql.zod.ts" />
1415
<Card href="./odata" title="Odata" description="Source: packages/spec/src/api/odata.zod.ts" />
1516
<Card href="./realtime" title="Realtime" description="Source: packages/spec/src/api/realtime.zod.ts" />
1617
<Card href="./router" title="Router" description="Source: packages/spec/src/api/router.zod.ts" />

‎content/docs/references/api/meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
"contract",
55
"discovery",
66
"endpoint",
7+
"graphql",
78
"odata",
89
"realtime",
910
"router"

0 commit comments

Comments
 (0)