Skip to content

Commit 5f8e325

Browse files
toptobestoptobes
committed
more documentation work + remove
1 parent c360911 commit 5f8e325

File tree

3 files changed

+221
-22
lines changed

3 files changed

+221
-22
lines changed

‎src/data-api/types/common.ts

Lines changed: 72 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -17,66 +17,121 @@ import type { ToDotNotation } from '@/src/data-api/types';
1717

1818
export type SomeId = string | number | bigint | boolean | Date | UUID | ObjectId;
1919

20-
export type Sort =
21-
| Record<string, 1 | -1>
22-
| { $vector: { $meta: number[] } }
23-
| { $vector: number[] }
24-
| { $vectorize: string };
25-
26-
export type Projection = Record<string, 1 | 0 | true | false | Slice>;
27-
2820
/**
2921
* Specifies the sort criteria for selecting documents.
3022
*
23+
* **If you want stricter type-checking and full auto-complete, see {@link StrictSort}.**
24+
*
3125
* Can use `1`/`-1` for ascending/descending, or `$vector` for sorting by vector distance.
3226
*
3327
* **NB. The order of the fields in the sort option is significant—fields are sorted in the order they are listed.**
3428
*
3529
* @example
3630
* ```typescript
3731
* // Sort by name in ascending order, then by age in descending order
38-
* const sort1: Sort<SomeDoc> = {
32+
* const sort1: Sort = {
3933
*   name: 1,
4034
*   age: -1,
4135
* }
4236
*
4337
* // Sort by vector distance
44-
* const sort2: Sort<SomeDoc> = {
38+
* const sort2: Sort = {
4539
*   $vector: [0.23, 0.38, 0.27, 0.91, 0.21],
4640
* }
4741
* ```
4842
*/
49-
export type StrictSort<Schema extends SomeDoc> =
50-
| { [K in keyof ToDotNotation<WithId<Schema>>]?: 1 | -1 }
51-
| { $vector: { $meta: number[] } }
43+
export type Sort =
44+
| Record<string, 1 | -1>
5245
| { $vector: number[] }
5346
| { $vectorize: string };
5447

5548
/**
5649
* Specifies which fields should be included/excluded in the returned documents.
5750
*
51+
* **If you want stricter type-checking and full auto-complete, see {@link StrictProjection}.**
52+
*
5853
* Can use `1`/`0`, or `true`/`false`
5954
*
6055
* @example
6156
* ```typescript
6257
* // Include _id, name, and address.state
63-
* const projection1: Projection<SomeDoc> = {
64-
*   _id: 1,
58+
* const projection1: Projection = {
59+
*   _id: 0,
6560
*   name: 1,
6661
*   'address.state': 1,
6762
* }
6863
*
6964
* // Exclude the $vector
70-
* const projection2: Projection<SomeDoc> = {
65+
* const projection2: Projection = {
7166
*   $vector: 0,
7267
* }
7368
*
7469
* // Return array indices 2, 3, 4, and 5
75-
* const projection3: Projection<SomeDoc> = {
70+
* const projection3: Projection = {
7671
*   test_scores: { $slice: [2, 4] },
7772
* }
7873
* ```
7974
*/
75+
export type Projection = Record<string, 1 | 0 | true | false | Slice>;
76+
77+
/**
78+
* Specifies the sort criteria for selecting documents.
79+
*
80+
* Can use `1`/`-1` for ascending/descending, or `$vector` for sorting by vector distance.
81+
*
82+
* **NB. The order of the fields in the sort option is significant—fields are sorted in the order they are listed.**
83+
*
84+
* @example
85+
* ```typescript
86+
* // Sort by name in ascending order, then by age in descending order
87+
* await collection.findOne({}, {
88+
*   sort: {
89+
*   name: 1,
90+
*   age: -1,
91+
*   } satisfies StrictSort<SomeDoc>,
92+
* });
93+
*
94+
* // Sort by vector distance
95+
* await collection.findOne({}, {
96+
*   sort: {
97+
*   $vector: [0.23, 0.38, 0.27, 0.91, 0.21],
98+
*   } satisfies StrictSort<SomeDoc>,
99+
* });
100+
* ```
101+
*/
102+
export type StrictSort<Schema extends SomeDoc> =
103+
| { [K in keyof ToDotNotation<WithId<Schema>>]?: 1 | -1 }
104+
| { $vector: number[] }
105+
| { $vectorize: string };
106+
107+
/**
108+
* Specifies which fields should be included/excluded in the returned documents.
109+
*
110+
* Can use `1`/`0`, or `true`/`false`
111+
*
112+
* @example
113+
* ```typescript
114+
* await collection.findOne({}, {
115+
*   projection: {
116+
*   _id: 0,
117+
*   name: 1,
118+
*   'address.state': 1,
119+
*   } satisfies StrictProjection<SomeDoc>,
120+
* });
121+
*
122+
* await collection.findOne({}, {
123+
*   projection: {
124+
*   $vector: 0,
125+
*   } satisfies StrictProjection<SomeDoc>,
126+
* });
127+
*
128+
* await collection.findOne({}, {
129+
*   projection: {
130+
*   test_scores: { $slice: [2, 4] },
131+
*   } satisfies StrictProjection<SomeDoc>,
132+
* });
133+
* ```
134+
*/
80135
export type StrictProjection<Schema extends SomeDoc> = {
81136
[K in keyof ToDotNotation<WithId<Schema>>]?: any[] extends (ToDotNotation<WithId<Schema>>)[K]
82137
? 1 | 0 | true | false | Slice

‎src/data-api/types/filter.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ import type { IdOf, IsDate, IsNum, NoId, ToDotNotation } from '@/src/data-api/ty
1818
/**
1919
* Represents some filter operation for a given document schema.
2020
*
21-
* **If you want stricter type-checking, see {@link StrictFilter}.**
21+
* **If you want stricter type-checking and full auto-complete, see {@link StrictFilter}.**
2222
*
2323
* This is a more relaxed version of {@link StrictFilter} that doesn't type-check nested fields.
2424
*

‎src/data-api/types/update-filter.ts

Lines changed: 148 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ import type { IsDate, IsNum, ToDotNotation } from '@/src/data-api/types';
1818
/**
1919
* Represents the update filter to specify how to update a document.
2020
*
21-
* **If you want stricter type-checking, see {@link StrictUpdateFilter}.**
21+
* **If you want stricter type-checking and full auto-complete, see {@link StrictUpdateFilter}.**
2222
*
2323
* This is a more relaxed version of {@link StrictUpdateFilter} that doesn't type-check nested fields.
2424
*
@@ -51,17 +51,161 @@ import type { IsDate, IsNum, ToDotNotation } from '@/src/data-api/types';
5151
* @field $addToSet - Add an element to an array field in the document if it does not already exist.
5252
*/
5353
export interface UpdateFilter<Schema extends SomeDoc> {
54+
/**
55+
* Set the value of a field in the document.
56+
*
57+
* @example
58+
* ```typescript
59+
* const updateFilter: UpdateFilter<SomeDoc> = {
60+
*   $set: {
61+
*   'customer.name': 'Jim B.'
62+
*   }
63+
* }
64+
* ```
65+
*/
5466
$set?: Partial<Schema> & SomeDoc,
67+
/**
68+
* Set the value of a field in the document if an upsert is performed.
69+
*
70+
* @example
71+
* ```typescript
72+
* const updateFilter: UpdateFilter<SomeDoc> = {
73+
*   $setOnInsert: {
74+
*   'customer.name': 'Jim B.'
75+
*   }
76+
* }
77+
* ```
78+
*/
5579
$setOnInsert?: Partial<Schema> & SomeDoc,
56-
$min?: (NumberUpdate<Schema> | DateUpdate<Schema>) & Record<string, number | bigint | Date | { $date: number }>,
57-
$max?: (NumberUpdate<Schema> | DateUpdate<Schema>) & Record<string, number | bigint | Date | { $date: number }>,
58-
$mul?: StrictNumberUpdate<Schema> & Record<string, number>,
80+
/**
81+
* Remove the field from the document.
82+
*
83+
* @example
84+
* ```typescript
85+
* const updateFilter: UpdateFilter<SomeDoc> = {
86+
*   $unset: {
87+
*   'customer.phone': ''
88+
*   }
89+
* }
90+
* ```
91+
*/
5992
$unset?: Record<string, ''>,
93+
/**
94+
* Increment the value of a field in the document if it's potentially a `number`.
95+
*
96+
* @example
97+
* ```typescript
98+
* const updateFilter: UpdateFilter<SomeDoc> = {
99+
*   $inc: {
100+
*   'customer.age': 1
101+
*   }
102+
* }
103+
* ```
104+
*/
60105
$inc?: NumberUpdate<Schema> & Record<string, number>,
106+
/**
107+
* Add an element to an array field in the document.
108+
*
109+
* @example
110+
* ```typescript
111+
* const updateFilter: UpdateFilter<SomeDoc> = {
112+
*   $push: {
113+
*   'items': 'Extended warranty - 5 years'
114+
*   }
115+
* }
116+
* ```
117+
*/
61118
$push?: Push<Schema> & SomeDoc,
119+
/**
120+
* Remove an element from an array field in the document.
121+
*
122+
* @example
123+
* ```typescript
124+
* const updateFilter: UpdateFilter<SomeDoc> = {
125+
*   $pop: {
126+
*   'items': -1
127+
*   }
128+
* }
129+
* ```
130+
*/
62131
$pop?: Pop<Schema> & Record<string, number>,
132+
/**
133+
* Rename a field in the document.
134+
*
135+
* @example
136+
* ```typescript
137+
* const updateFilter: UpdateFilter<SomeDoc> = {
138+
*   $rename: {
139+
*   'customer.name': 'client.name'
140+
*   }
141+
* }
142+
* ```
143+
*/
63144
$rename?: Record<string, string>,
145+
/**
146+
* Set the value of a field to the current date.
147+
*
148+
* @example
149+
* ```typescript
150+
* const updateFilter: UpdateFilter<SomeDoc> = {
151+
*   $currentDate: {
152+
*   'purchase_date': true
153+
*   }
154+
* }
155+
* ```
156+
*/
64157
$currentDate?: CurrentDate<Schema> & Record<string, boolean>,
158+
/**
159+
* Only update the field if the specified value is less than the existing value.
160+
*
161+
* @example
162+
* ```typescript
163+
* const updateFilter: UpdateFilter<SomeDoc> = {
164+
*   $min: {
165+
*   'customer.age': 18
166+
*   }
167+
* }
168+
* ```
169+
*/
170+
$min?: (NumberUpdate<Schema> | DateUpdate<Schema>) & Record<string, number | bigint | Date | { $date: number }>,
171+
/**
172+
* Only update the field if the specified value is greater than the existing value.
173+
*
174+
* @example
175+
* ```typescript
176+
* const updateFilter: UpdateFilter<SomeDoc> = {
177+
*   $max: {
178+
*   'customer.age': 65
179+
*   }
180+
* }
181+
* ```
182+
*/
183+
$max?: (NumberUpdate<Schema> | DateUpdate<Schema>) & Record<string, number | bigint | Date | { $date: number }>,
184+
/**
185+
* Multiply the value of a field in the document.
186+
*
187+
* @example
188+
* ```typescript
189+
* const updateFilter: UpdateFilter<SomeDoc> = {
190+
*   $mul: {
191+
*   'customer.age': 1.1
192+
*   }
193+
* }
194+
* ```
195+
*/
196+
$mul?: StrictNumberUpdate<Schema> & Record<string, number>,
197+
/**
198+
* Add an element to an array field in the document if it does not already exist.
199+
*
200+
* @example
201+
* ```typescript
202+
* const updateFilter: UpdateFilter<SomeDoc> = {
203+
*   $addToSet: {
204+
*   'items': 'Extended warranty - 5 years'
205+
*   }
206+
* }
207+
* ```
208+
*/
65209
$addToSet?: Push<Schema> & SomeDoc,
66210
}
67211

0 commit comments

Comments
 (0)