Skip to content

Commit b66373c

Browse files
ymc9ymc9
authored
doc: release beta.26 (#517)
1 parent 3e7bb45 commit b66373c

File tree

2 files changed

+205
-56
lines changed

2 files changed

+205
-56
lines changed

‎versioned_docs/version-3.x/orm/api/omit.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
sidebar_position: 10
3+
description: Omitting Fields
4+
---
5+
6+
import StackBlitzGithub from '@site/src/components/StackBlitzGithub';
7+
8+
# Omitting Fields
9+
10+
The previous sections have shown how you can use `select` and `omit` clauses to control the fields returned in the query results. There may be scenarios where you want to exclude certain fields (e.g., `password`) for most queries. ZenStack provides a mechanism to configure field omission in a hierarchical manner.
11+
12+
:::info
13+
Please note that the omit settings only affect the ORM query APIs, but not the [Query Builder APIs](../query-builder). With query builder you'll need to explicitly specify the fields to select.
14+
:::
15+
16+
## Schema-Level Omit
17+
18+
You can use the `@omit` attribute in ZModel to mark fields to be omitted. Such fields will be omitted by default for all `ZenStackClient` instances and all queries.
19+
20+
```zmodel
21+
model User {
22+
id Int @id
23+
name String
24+
email String @unique
25+
password String @omit
26+
}
27+
```
28+
29+
## Client-Level Omit
30+
31+
When creating a `ZenStackClient`, you can customize what fields to omit by specifying the `omit` option.
32+
33+
```ts
34+
const db = new ZenStackClient<Schema>({
35+
...
36+
omit: {
37+
User: { email: true }
38+
},
39+
});
40+
```
41+
42+
You can also use the `$setOptions` API to create a shallow clone of an existing client with different options:
43+
44+
```ts
45+
const db = new ZenStackClient<Schema>({ ... });
46+
const dbNoEmail = db.$setOptions({
47+
...db.$options,
48+
omit: {
49+
User: { email: true }
50+
},
51+
});
52+
```
53+
54+
## Query-Level Omit
55+
56+
Finally, at query time you can use the `omit` clause for per-query control.
57+
58+
```ts
59+
const users = await db.user.findMany({
60+
omit: { name: true },
61+
});
62+
```
63+
64+
## Precedence and Overrides
65+
66+
The precedence of omit settings is: query-level > client-level > schema-level. A higher precedence setting can override a lower one and re-include a field by negating the omit flag. E.g., at query time you can re-include the `password` field that was omitted at schema level:
67+
68+
```ts
69+
const users = await db.user.findMany({
70+
omit: { password: false },
71+
});
72+
```
73+
74+
There might be scenarios where you don't want the query-level override feature. For example, when using `ZenStackClient` with the [Query as a Service](../../service), you may want to have certain fields always omitted for security reasons. In such cases, use the `allowQueryTimeOmitOverride` option to disable query-time overrides:
75+
76+
```ts
77+
const db = new ZenStackClient<Schema>({
78+
...
79+
allowQueryTimeOmitOverride: false,
80+
});
81+
```
82+
83+
When this option set to `false`, any attempt to negate an omission at query time will trigger a validation error.
84+
85+
```ts
86+
// This will throw an error because query-time override is disabled.
87+
const users = await db.user.findMany({
88+
omit: { password: false },
89+
});
90+
```
91+

‎versioned_docs/version-3.x/reference/api.md‎

Lines changed: 114 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ sidebar_label: API
1010

1111
### `ClientContract<Schema>`
1212

13-
The interface for the ZenStack ORM client, implemented by [ZenStackClient](#zenstackclient).
13+
The interface for the ZenStack ORM client, implemented by [ZenStackClient](#zenstackclientschema).
1414

1515
### `ZenStackClient<Schema>`
1616

@@ -21,43 +21,118 @@ The class that implements the ORM client.
2121
* ZenStack ORM client.
2222
*/
2323
export const ZenStackClient = function <Schema extends SchemaDef>(
24-
this: any,
25-
schema: Schema,
26-
options: ClientOptions<Schema>,
24+
this: any,
25+
schema: Schema,
26+
options: ClientOptions<Schema>,
2727
);
28+
```
29+
30+
#### Options
2831

32+
```ts
2933
/**
3034
* ZenStack client options.
3135
*/
3236
export type ClientOptions<Schema extends SchemaDef> = {
33-
/**
34-
* Kysely dialect.
35-
*/
36-
dialect: Dialect;
37-
38-
/**
39-
* Plugins.
40-
*/
41-
plugins?: RuntimePlugin<Schema>[];
42-
43-
/**
44-
* Logging configuration.
45-
*/
46-
log?: KyselyConfig['log'];
47-
48-
// only required when using computed fields
49-
/**
50-
* Computed field definitions.
51-
*/
52-
computedFields: ComputedFieldsOptions<Schema>;
37+
/**
38+
* Kysely dialect.
39+
*/
40+
dialect: Dialect;
41+
42+
/**
43+
* Plugins.
44+
*/
45+
plugins?: RuntimePlugin<Schema>[];
46+
47+
/**
48+
* Logging configuration.
49+
*/
50+
log?: KyselyConfig['log'];
51+
52+
/**
53+
* Whether to automatically fix timezone for `DateTime` fields returned by
54+
* node-pg. Defaults to `true`.
55+
*
56+
* Node-pg has a terrible quirk that it interprets the date value as local
57+
* timezone (as a `Date` object) although for `DateTime` field the data in
58+
* DB is stored in UTC.
59+
* @see https://github.com/brianc/node-postgres/issues/429
60+
*/
61+
fixPostgresTimezone?: boolean;
62+
63+
/**
64+
* Whether to enable input validations expressed with attributes like `@email`,
65+
* `@regex`, `@@validate`, etc. Defaults to `true`.
66+
*/
67+
validateInput?: boolean;
68+
69+
/**
70+
* Options for omitting fields in ORM query results.
71+
*/
72+
omit?: OmitOptions<Schema>;
73+
74+
/**
75+
* Computed field definitions.
76+
*/
77+
computedFields?: ComputedFieldsOptions<Schema>;
5378
};
5479
```
5580

56-
#### Query APIs
81+
#### Properties
82+
83+
##### `$schema`
84+
85+
```ts
86+
/**
87+
* The schema definition.
88+
*/
89+
readonly $schema: Schema;
90+
```
91+
92+
##### `$options`
93+
```ts
94+
/**
95+
* The client options.
96+
*/
97+
readonly $options: Options;
98+
```
99+
100+
##### `$auth`
101+
102+
```ts
103+
/**
104+
* The current user identity.
105+
*/
106+
get $auth(): AuthType<Schema> | undefined;
107+
```
108+
109+
##### `$qb`
110+
111+
Read more in the [Query Builder API documentation](../orm/query-builder).
112+
113+
```ts
114+
/**
115+
* The underlying Kysely query builder instance.
116+
*/
117+
readonly $qb: ToKysely<Schema>;
118+
```
119+
120+
##### `$qbRaw`
121+
122+
Read more in the [Query Builder API documentation](../orm/query-builder).
123+
124+
```ts
125+
/**
126+
* The underlying raw Kysely query builder without any ZenStack enhancements.
127+
*/
128+
readonly $qbRaw: AnyKysely;
129+
```
130+
131+
#### APIs
57132

58-
Please refer to the [ORM Query API documentation](../orm/api/) for more details about query APIs like `findMany`, `create`, `update`, etc.
133+
Please refer to the [ORM Query API documentation](../orm/api/) for more details about CRUD APIs like `findMany`, `create`, `update`, etc.
59134

60-
#### `$connect()`
135+
##### `$connect()`
61136

62137
```ts
63138
/**
@@ -66,7 +141,7 @@ Please refer to the [ORM Query API documentation](../orm/api/) for more details
66141
$connect(): Promise<void>;
67142
```
68143

69-
#### `$disconnect()`
144+
##### `$disconnect()`
70145

71146
```ts
72147
/**
@@ -75,7 +150,7 @@ $connect(): Promise<void>;
75150
$disconnect(): Promise<void>;
76151
```
77152

78-
#### `$setAuth()`
153+
##### `$setAuth()`
79154

80155
```ts
81156
/**
@@ -84,16 +159,20 @@ $disconnect(): Promise<void>;
84159
$setAuth(auth: AuthType<Schema> | undefined): ClientContract<Schema>;
85160
```
86161

87-
#### `$auth`
162+
##### `$setOptions`
88163

89164
```ts
90165
/**
91-
* The current user identity.
166+
* Returns a new client with new options applied.
167+
* @example
168+
* ```
169+
* const dbNoValidation = db.$setOptions({ ...db.$options, validateInput: false });
170+
* ```
92171
*/
93-
get $auth(): AuthType<Schema> | undefined;
172+
$setOptions<Options extends ClientOptions<Schema>>(options: Options): ClientContract<Schema, Options>;
94173
```
95174
96-
#### `$use()`
175+
##### `$use()`
97176
98177
Read more in the [Plugins documentation](../orm/plugins/).
99178
@@ -104,7 +183,7 @@ Read more in the [Plugins documentation](../orm/plugins/).
104183
$use(plugin: RuntimePlugin<Schema>): ClientContract<Schema>;
105184
```
106185
107-
#### `$unuse()`
186+
##### `$unuse()`
108187
109188
Read more in the [Plugins documentation](../orm/plugins/).
110189
@@ -115,7 +194,7 @@ Read more in the [Plugins documentation](../orm/plugins/).
115194
$unuse(pluginId: string): ClientContract<Schema>;
116195
```
117196
118-
#### `$unuseAll()`
197+
##### `$unuseAll()`
119198
120199
Read more in the [Plugins documentation](../orm/plugins/).
121200
@@ -126,24 +205,3 @@ Read more in the [Plugins documentation](../orm/plugins/).
126205
$unuseAll(): ClientContract<Schema>;
127206
```
128207
129-
#### `$qb`
130-
131-
Read more in the [Query Builder API documentation](../orm/query-builder).
132-
133-
```ts
134-
/**
135-
* The underlying Kysely query builder instance.
136-
*/
137-
readonly $qb: ToKysely<Schema>;
138-
```
139-
140-
#### `$qbRaw`
141-
142-
Read more in the [Query Builder API documentation](../orm/query-builder).
143-
144-
```ts
145-
/**
146-
* The underlying raw Kysely query builder without any ZenStack enhancements.
147-
*/
148-
readonly $qbRaw: AnyKysely;
149-
```

0 commit comments

Comments
 (0)