/
Containers.ts
205 lines (195 loc) · 7.91 KB
/
Containers.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.
import { ClientContext } from "../../ClientContext";
import {
Constants,
getIdFromLink,
getPathFromLink,
isResourceValid,
ResourceType,
StatusCodes
} from "../../common";
import { DEFAULT_PARTITION_KEY_PATH } from "../../common/partitionKeys";
import { mergeHeaders, SqlQuerySpec } from "../../queryExecutionContext";
import { QueryIterator } from "../../queryIterator";
import { FeedOptions, RequestOptions } from "../../request";
import { Database } from "../Database";
import { Resource } from "../Resource";
import { Container } from "./Container";
import { ContainerDefinition } from "./ContainerDefinition";
import { ContainerRequest } from "./ContainerRequest";
import { ContainerResponse } from "./ContainerResponse";
/**
* Operations for creating new containers, and reading/querying all containers
*
* @see {@link Container} for reading, replacing, or deleting an existing container; use `.container(id)`.
*
* Note: all these operations make calls against a fixed budget.
* You should design your system such that these calls scale sublinearly with your application.
* For instance, do not call `containers.readAll()` before every single `item.read()` call, to ensure the container exists;
* do this once on application start up.
*/
export class Containers {
constructor(public readonly database: Database, private readonly clientContext: ClientContext) {}
/**
* Queries all containers.
* @param query Query configuration for the operation. See {@link SqlQuerySpec} for more info on how to configure a query.
* @param options Use to set options like response page size, continuation tokens, etc.
* @returns {@link QueryIterator} Allows you to return specific contaienrs in an array or iterate over them one at a time.
* @example Read all containers to array.
* ```typescript
* const querySpec: SqlQuerySpec = {
* query: "SELECT * FROM root r WHERE r.id = @container",
* parameters: [
* {name: "@container", value: "Todo"}
* ]
* };
* const {body: containerList} = await client.database("<db id>").containers.query(querySpec).fetchAll();
* ```
*/
public query(query: SqlQuerySpec, options?: FeedOptions): QueryIterator<any>;
/**
* Queries all containers.
* @param query Query configuration for the operation. See {@link SqlQuerySpec} for more info on how to configure a query.
* @param options Use to set options like response page size, continuation tokens, etc.
* @returns {@link QueryIterator} Allows you to return specific contaienrs in an array or iterate over them one at a time.
* @example Read all containers to array.
* ```typescript
* const querySpec: SqlQuerySpec = {
* query: "SELECT * FROM root r WHERE r.id = @container",
* parameters: [
* {name: "@container", value: "Todo"}
* ]
* };
* const {body: containerList} = await client.database("<db id>").containers.query(querySpec).fetchAll();
* ```
*/
public query<T>(query: SqlQuerySpec, options?: FeedOptions): QueryIterator<T>;
public query<T>(query: SqlQuerySpec, options?: FeedOptions): QueryIterator<T> {
const path = getPathFromLink(this.database.url, ResourceType.container);
const id = getIdFromLink(this.database.url);
return new QueryIterator(this.clientContext, query, options, (innerOptions) => {
return this.clientContext.queryFeed<ContainerDefinition>({
path,
resourceType: ResourceType.container,
resourceId: id,
resultFn: (result) => result.DocumentCollections,
query,
options: innerOptions
});
});
}
/**
* Creates a container.
*
* A container is a named logical container for items.
*
* A database may contain zero or more named containers and each container consists of
* zero or more JSON items.
*
* Being schema-free, the items in a container do not need to share the same structure or fields.
*
*
* Since containers are application resources, they can be authorized using either the
* master key or resource keys.
*
* @param body Represents the body of the container.
* @param options Use to set options like response page size, continuation tokens, etc.
*/
public async create(
body: ContainerRequest,
options: RequestOptions = {}
): Promise<ContainerResponse> {
const err = {};
if (!isResourceValid(body, err)) {
throw err;
}
const path = getPathFromLink(this.database.url, ResourceType.container);
const id = getIdFromLink(this.database.url);
if (body.throughput) {
options.initialHeaders = Object.assign({}, options.initialHeaders, {
[Constants.HttpHeaders.OfferThroughput]: body.throughput
});
delete body.throughput;
}
if (typeof body.partitionKey === "string") {
if (!body.partitionKey.startsWith("/")) {
throw new Error("Partition key must start with '/'");
}
body.partitionKey = {
paths: [body.partitionKey]
};
}
// If they don't specify a partition key, use the default path
if (!body.partitionKey || !body.partitionKey.paths) {
body.partitionKey = {
paths: [DEFAULT_PARTITION_KEY_PATH]
};
}
const response = await this.clientContext.create<ContainerRequest, ContainerDefinition>({
body,
path,
resourceType: ResourceType.container,
resourceId: id,
options
});
const ref = new Container(this.database, response.result.id, this.clientContext);
return new ContainerResponse(response.result, response.headers, response.code, ref);
}
/**
* Checks if a Container exists, and, if it doesn't, creates it.
* This will make a read operation based on the id in the `body`, then if it is not found, a create operation.
* You should confirm that the output matches the body you passed in for non-default properties (i.e. indexing policy/etc.)
*
* A container is a named logical container for items.
*
* A database may contain zero or more named containers and each container consists of
* zero or more JSON items.
*
* Being schema-free, the items in a container do not need to share the same structure or fields.
*
*
* Since containers are application resources, they can be authorized using either the
* master key or resource keys.
*
* @param body Represents the body of the container.
* @param options Use to set options like response page size, continuation tokens, etc.
*/
public async createIfNotExists(
body: ContainerRequest,
options?: RequestOptions
): Promise<ContainerResponse> {
if (!body || body.id === null || body.id === undefined) {
throw new Error("body parameter must be an object with an id property");
}
/*
1. Attempt to read the Container (based on an assumption that most containers will already exist, so its faster)
2. If it fails with NotFound error, attempt to create the container. Else, return the read results.
*/
try {
const readResponse = await this.database.container(body.id).read(options);
return readResponse;
} catch (err) {
if (err.code === StatusCodes.NotFound) {
const createResponse = await this.create(body, options);
// Must merge the headers to capture RU costskaty
mergeHeaders(createResponse.headers, err.headers);
return createResponse;
} else {
throw err;
}
}
}
/**
* Read all containers.
* @param options Use to set options like response page size, continuation tokens, etc.
* @returns {@link QueryIterator} Allows you to return all containers in an array or iterate over them one at a time.
* @example Read all containers to array.
* ```typescript
* const {body: containerList} = await client.database("<db id>").containers.readAll().fetchAll();
* ```
*/
public readAll(options?: FeedOptions): QueryIterator<ContainerDefinition & Resource> {
return this.query(undefined, options);
}
}