@infra-blocks/aws-dynamodb 0.1.1-alpha.1 → 0.2.0-alpha.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/cjs/src/client.d.ts +116 -15
- package/lib/cjs/src/client.js +115 -39
- package/lib/cjs/src/client.js.map +1 -1
- package/lib/esm/src/client.d.ts +116 -15
- package/lib/esm/src/client.js +117 -41
- package/lib/esm/src/client.js.map +1 -1
- package/package.json +1 -1
package/lib/cjs/src/client.d.ts
CHANGED
|
@@ -1,15 +1,43 @@
|
|
|
1
1
|
import type { DynamoDBClientConfig } from "@aws-sdk/client-dynamodb";
|
|
2
|
-
import { DynamoDBClient as BaseClient } from "@aws-sdk/client-dynamodb";
|
|
3
2
|
import type { TranslateConfig } from "@aws-sdk/lib-dynamodb";
|
|
4
|
-
import { DynamoDBDocumentClient
|
|
3
|
+
import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
|
|
5
4
|
import type { Logger } from "@infra-blocks/logger-interface";
|
|
6
5
|
import { type Retry, type RetryConfig } from "@infra-blocks/retry";
|
|
7
6
|
import type { Attributes, GetItem, PutItem, Query, WriteTransaction } from "./types.js";
|
|
7
|
+
/**
|
|
8
|
+
* Creation parameters for the {@link DynamoDbClient}.
|
|
9
|
+
*/
|
|
10
|
+
export type CreateParams = {
|
|
11
|
+
/**
|
|
12
|
+
* The configuration for the vanilly DynamoDB client.
|
|
13
|
+
*
|
|
14
|
+
* When none is provided, the client is instantiated with the default configuration
|
|
15
|
+
* provided by the AWS SDK.
|
|
16
|
+
*/
|
|
17
|
+
dynamodb?: DynamoDBClientConfig;
|
|
18
|
+
/**
|
|
19
|
+
* The configuration for the document client.
|
|
20
|
+
*
|
|
21
|
+
* When none is provided, the document client is instantiated with the default
|
|
22
|
+
* configuration provided by the AWS SDK.
|
|
23
|
+
*/
|
|
24
|
+
document?: TranslateConfig;
|
|
25
|
+
/**
|
|
26
|
+
* Optional logger to use for logging.
|
|
27
|
+
*
|
|
28
|
+
* When none is provided, a {@link NullLogger} is used, which logs into the void.
|
|
29
|
+
*/
|
|
30
|
+
logger?: Logger;
|
|
31
|
+
};
|
|
8
32
|
export declare class DynamoDbClientError extends Error {
|
|
9
33
|
constructor(message: string, options?: {
|
|
10
34
|
cause?: unknown;
|
|
11
35
|
});
|
|
12
36
|
}
|
|
37
|
+
/**
|
|
38
|
+
* Wrapper class around the {@link DynamoDBDocumentClient} that provides added functionality,
|
|
39
|
+
* safer types and some convenience methods.
|
|
40
|
+
*/
|
|
13
41
|
export declare class DynamoDbClient {
|
|
14
42
|
private readonly client;
|
|
15
43
|
private readonly logger;
|
|
@@ -36,22 +64,95 @@ export declare class DynamoDbClient {
|
|
|
36
64
|
* @see https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html
|
|
37
65
|
*/
|
|
38
66
|
getItem<T>(params: GetItem): Promise<T | undefined>;
|
|
67
|
+
/**
|
|
68
|
+
* Puts an item using the PutItem API.
|
|
69
|
+
*
|
|
70
|
+
* Refer to the API documentation for more details on how it works. Basically, without
|
|
71
|
+
* conditions, this function will either insert a new document or *replace* the existing
|
|
72
|
+
* one with whatever attributes are provided.
|
|
73
|
+
*
|
|
74
|
+
* @param params - The parameters to use to put the item.
|
|
75
|
+
*
|
|
76
|
+
* @see https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html
|
|
77
|
+
*/
|
|
39
78
|
putItem(params: PutItem): Promise<void>;
|
|
79
|
+
/**
|
|
80
|
+
* Queries a table, or an index, using the Query API.
|
|
81
|
+
*
|
|
82
|
+
* Pagination is automatically handled as an async generator, yielding
|
|
83
|
+
* one item at a time.
|
|
84
|
+
*
|
|
85
|
+
* @param params - The parameters to use to query the table or index.
|
|
86
|
+
*
|
|
87
|
+
* @returns An async generator that yields items matching the query, one
|
|
88
|
+
* at a time, and that handles pagination automatically.
|
|
89
|
+
*
|
|
90
|
+
* @see https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html
|
|
91
|
+
*/
|
|
92
|
+
query<T extends Attributes = Attributes>(params: Query): AsyncGenerator<T>;
|
|
93
|
+
/**
|
|
94
|
+
* Convenience method over the {@link query} method enforcing that the query
|
|
95
|
+
* matches at most one item.
|
|
96
|
+
*
|
|
97
|
+
* If the query doesn't match any item, then `undefined` is returned. If there are
|
|
98
|
+
* matches, then the function throws as soon as a second matching item is returned.
|
|
99
|
+
*
|
|
100
|
+
* @param params - The parameters to use to query the table or index.
|
|
101
|
+
*
|
|
102
|
+
* @returns The only item matching the query, or `undefined` if no item matches.
|
|
103
|
+
*/
|
|
104
|
+
queryOne<T extends Attributes = Attributes>(params: Query): Promise<T | undefined>;
|
|
105
|
+
/**
|
|
106
|
+
* Executes a write transaction using the TransactWriteItems API.
|
|
107
|
+
*
|
|
108
|
+
* @param params - The parameters describing the transaction.
|
|
109
|
+
*
|
|
110
|
+
* @see https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html
|
|
111
|
+
*/
|
|
40
112
|
transactWriteItems(params: WriteTransaction): Promise<void>;
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
113
|
+
/**
|
|
114
|
+
* Alias for the {@link putItem} method.
|
|
115
|
+
*/
|
|
116
|
+
upsert: (params: PutItem) => Promise<void>;
|
|
117
|
+
/**
|
|
118
|
+
* Creates an instance of the {@link DynamoDbClient} wrapping the provided document
|
|
119
|
+
* client directly.
|
|
120
|
+
*
|
|
121
|
+
* This is useful when the user has already created a document client, or when the document
|
|
122
|
+
* client is a mock for testing purposes. Otherwise, {@link DynamoDbClient.create} should be
|
|
123
|
+
* preferred.
|
|
124
|
+
*
|
|
125
|
+
* @param params - The creation parameters.
|
|
126
|
+
*
|
|
127
|
+
* @returns A new instance of the {@link DynamoDbClient} wrapping the provided document client.
|
|
128
|
+
*/
|
|
48
129
|
static from(params: {
|
|
49
|
-
client:
|
|
50
|
-
logger?: Logger;
|
|
51
|
-
}): DynamoDbClient;
|
|
52
|
-
static create(params?: {
|
|
53
|
-
base?: DynamoDBClientConfig;
|
|
54
|
-
document?: TranslateConfig;
|
|
130
|
+
client: DynamoDBDocumentClient;
|
|
55
131
|
logger?: Logger;
|
|
56
132
|
}): DynamoDbClient;
|
|
133
|
+
/**
|
|
134
|
+
* Creates an instance of the {@link DynamoDbClient} using the provided parameters.
|
|
135
|
+
*
|
|
136
|
+
* The client is a wrapper around the {@link DynamoDBDocumentClient} from the `@aws-sdk/lib-dynamodb`
|
|
137
|
+
* package, which is itself a wrapper around the {@link DynamoDBClient} from the
|
|
138
|
+
* `@aws-sdk/client-dynamodb` package.
|
|
139
|
+
*
|
|
140
|
+
* This factory function first intantiates the vanilla client with optionally provided
|
|
141
|
+
* configuration, then wraps it in a {@link DynamoDBDocumentClient} that can also
|
|
142
|
+
* be configured. When no configuration is used, both clients are created using their
|
|
143
|
+
* respective default configuration.
|
|
144
|
+
*
|
|
145
|
+
* The DynamoDB vanilla client can be configured using the `dynamodb` parameter,
|
|
146
|
+
* The document client can be configured using the `document` parameter,
|
|
147
|
+
*
|
|
148
|
+
* The `logger` parameter is optional and defaults to a {@link NullLogger}.
|
|
149
|
+
*
|
|
150
|
+
* The user also has the option to create and configure the document client outside of this code
|
|
151
|
+
* and use the {@link DynamoDbClient.from} method wrap it with a fresh instance of this class.
|
|
152
|
+
*
|
|
153
|
+
* @param params - The creation parameters.
|
|
154
|
+
*
|
|
155
|
+
* @returns A new instance of the {@link DynamoDbClient}.
|
|
156
|
+
*/
|
|
157
|
+
static create(params?: CreateParams): DynamoDbClient;
|
|
57
158
|
}
|
package/lib/cjs/src/client.js
CHANGED
|
@@ -12,13 +12,10 @@ class DynamoDbClientError extends Error {
|
|
|
12
12
|
}
|
|
13
13
|
}
|
|
14
14
|
exports.DynamoDbClientError = DynamoDbClientError;
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
This is to say, we can create items in a different table that only has a pk for this specific use case, or we could
|
|
20
|
-
also use the same table. It's just going to add some sheeet to the table.
|
|
21
|
-
*/
|
|
15
|
+
/**
|
|
16
|
+
* Wrapper class around the {@link DynamoDBDocumentClient} that provides added functionality,
|
|
17
|
+
* safer types and some convenience methods.
|
|
18
|
+
*/
|
|
22
19
|
class DynamoDbClient {
|
|
23
20
|
client;
|
|
24
21
|
logger;
|
|
@@ -81,6 +78,17 @@ class DynamoDbClient {
|
|
|
81
78
|
});
|
|
82
79
|
}
|
|
83
80
|
}
|
|
81
|
+
/**
|
|
82
|
+
* Puts an item using the PutItem API.
|
|
83
|
+
*
|
|
84
|
+
* Refer to the API documentation for more details on how it works. Basically, without
|
|
85
|
+
* conditions, this function will either insert a new document or *replace* the existing
|
|
86
|
+
* one with whatever attributes are provided.
|
|
87
|
+
*
|
|
88
|
+
* @param params - The parameters to use to put the item.
|
|
89
|
+
*
|
|
90
|
+
* @see https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html
|
|
91
|
+
*/
|
|
84
92
|
async putItem(params) {
|
|
85
93
|
try {
|
|
86
94
|
await this.client.send(toPutCommand(params));
|
|
@@ -92,27 +100,25 @@ class DynamoDbClient {
|
|
|
92
100
|
});
|
|
93
101
|
}
|
|
94
102
|
}
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
}
|
|
110
|
-
async *query(query) {
|
|
103
|
+
/**
|
|
104
|
+
* Queries a table, or an index, using the Query API.
|
|
105
|
+
*
|
|
106
|
+
* Pagination is automatically handled as an async generator, yielding
|
|
107
|
+
* one item at a time.
|
|
108
|
+
*
|
|
109
|
+
* @param params - The parameters to use to query the table or index.
|
|
110
|
+
*
|
|
111
|
+
* @returns An async generator that yields items matching the query, one
|
|
112
|
+
* at a time, and that handles pagination automatically.
|
|
113
|
+
*
|
|
114
|
+
* @see https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html
|
|
115
|
+
*/
|
|
116
|
+
async *query(params) {
|
|
111
117
|
try {
|
|
112
|
-
const { expression, attributeValues } =
|
|
118
|
+
const { expression, attributeValues } = params.condition.toJson();
|
|
113
119
|
let response = await this.client.send(new lib_dynamodb_1.QueryCommand({
|
|
114
|
-
TableName:
|
|
115
|
-
IndexName:
|
|
120
|
+
TableName: params.table,
|
|
121
|
+
IndexName: params.index,
|
|
116
122
|
KeyConditionExpression: expression,
|
|
117
123
|
ExpressionAttributeValues: attributeValues,
|
|
118
124
|
}));
|
|
@@ -121,8 +127,8 @@ class DynamoDbClient {
|
|
|
121
127
|
}
|
|
122
128
|
while (response.LastEvaluatedKey != null) {
|
|
123
129
|
response = await this.client.send(new lib_dynamodb_1.QueryCommand({
|
|
124
|
-
TableName:
|
|
125
|
-
IndexName:
|
|
130
|
+
TableName: params.table,
|
|
131
|
+
IndexName: params.index,
|
|
126
132
|
KeyConditionExpression: expression,
|
|
127
133
|
ExpressionAttributeValues: attributeValues,
|
|
128
134
|
ExclusiveStartKey: response.LastEvaluatedKey,
|
|
@@ -133,15 +139,26 @@ class DynamoDbClient {
|
|
|
133
139
|
}
|
|
134
140
|
}
|
|
135
141
|
catch (err) {
|
|
136
|
-
throw new DynamoDbClientError(
|
|
142
|
+
throw new DynamoDbClientError(`error while querying DynamoDB on table ${params.table}${params.index != null ? ` and index ${params.index}` : ""}`, {
|
|
137
143
|
cause: err,
|
|
138
144
|
});
|
|
139
145
|
}
|
|
140
146
|
}
|
|
141
|
-
|
|
147
|
+
/**
|
|
148
|
+
* Convenience method over the {@link query} method enforcing that the query
|
|
149
|
+
* matches at most one item.
|
|
150
|
+
*
|
|
151
|
+
* If the query doesn't match any item, then `undefined` is returned. If there are
|
|
152
|
+
* matches, then the function throws as soon as a second matching item is returned.
|
|
153
|
+
*
|
|
154
|
+
* @param params - The parameters to use to query the table or index.
|
|
155
|
+
*
|
|
156
|
+
* @returns The only item matching the query, or `undefined` if no item matches.
|
|
157
|
+
*/
|
|
158
|
+
async queryOne(params) {
|
|
142
159
|
try {
|
|
143
160
|
let item;
|
|
144
|
-
for await (const queryItem of this.query(
|
|
161
|
+
for await (const queryItem of this.query(params)) {
|
|
145
162
|
if (item != null) {
|
|
146
163
|
throw new DynamoDbClientError("expected one item in query but found at least 2");
|
|
147
164
|
}
|
|
@@ -151,24 +168,83 @@ class DynamoDbClient {
|
|
|
151
168
|
}
|
|
152
169
|
catch (err) {
|
|
153
170
|
// TODO: careful here as email is PII.
|
|
154
|
-
throw new DynamoDbClientError(`error while querying one: ${JSON.stringify(
|
|
171
|
+
throw new DynamoDbClientError(`error while querying one: ${JSON.stringify(params)}`, {
|
|
155
172
|
cause: err,
|
|
156
173
|
});
|
|
157
174
|
}
|
|
158
175
|
}
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
176
|
+
/**
|
|
177
|
+
* Executes a write transaction using the TransactWriteItems API.
|
|
178
|
+
*
|
|
179
|
+
* @param params - The parameters describing the transaction.
|
|
180
|
+
*
|
|
181
|
+
* @see https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html
|
|
182
|
+
*/
|
|
183
|
+
async transactWriteItems(params) {
|
|
184
|
+
try {
|
|
185
|
+
const commandInput = toTransactWriteItemsCommandInput(params);
|
|
186
|
+
if (this.logger.isDebugEnabled()) {
|
|
187
|
+
this.logger.debug("executing transaction write: %s", JSON.stringify(commandInput));
|
|
188
|
+
}
|
|
189
|
+
const command = new lib_dynamodb_1.TransactWriteCommand(commandInput);
|
|
190
|
+
await this.client.send(command);
|
|
191
|
+
}
|
|
192
|
+
catch (err) {
|
|
193
|
+
throw new DynamoDbClientError("error while transactionally writing items in DynamoDB", {
|
|
194
|
+
cause: err,
|
|
195
|
+
});
|
|
196
|
+
}
|
|
163
197
|
}
|
|
198
|
+
/**
|
|
199
|
+
* Alias for the {@link putItem} method.
|
|
200
|
+
*/
|
|
201
|
+
upsert = this.putItem;
|
|
202
|
+
/**
|
|
203
|
+
* Creates an instance of the {@link DynamoDbClient} wrapping the provided document
|
|
204
|
+
* client directly.
|
|
205
|
+
*
|
|
206
|
+
* This is useful when the user has already created a document client, or when the document
|
|
207
|
+
* client is a mock for testing purposes. Otherwise, {@link DynamoDbClient.create} should be
|
|
208
|
+
* preferred.
|
|
209
|
+
*
|
|
210
|
+
* @param params - The creation parameters.
|
|
211
|
+
*
|
|
212
|
+
* @returns A new instance of the {@link DynamoDbClient} wrapping the provided document client.
|
|
213
|
+
*/
|
|
164
214
|
static from(params) {
|
|
165
215
|
const { client, logger = null_logger_1.NullLogger.create() } = params;
|
|
166
216
|
return new DynamoDbClient({ client, logger });
|
|
167
217
|
}
|
|
218
|
+
/**
|
|
219
|
+
* Creates an instance of the {@link DynamoDbClient} using the provided parameters.
|
|
220
|
+
*
|
|
221
|
+
* The client is a wrapper around the {@link DynamoDBDocumentClient} from the `@aws-sdk/lib-dynamodb`
|
|
222
|
+
* package, which is itself a wrapper around the {@link DynamoDBClient} from the
|
|
223
|
+
* `@aws-sdk/client-dynamodb` package.
|
|
224
|
+
*
|
|
225
|
+
* This factory function first intantiates the vanilla client with optionally provided
|
|
226
|
+
* configuration, then wraps it in a {@link DynamoDBDocumentClient} that can also
|
|
227
|
+
* be configured. When no configuration is used, both clients are created using their
|
|
228
|
+
* respective default configuration.
|
|
229
|
+
*
|
|
230
|
+
* The DynamoDB vanilla client can be configured using the `dynamodb` parameter,
|
|
231
|
+
* The document client can be configured using the `document` parameter,
|
|
232
|
+
*
|
|
233
|
+
* The `logger` parameter is optional and defaults to a {@link NullLogger}.
|
|
234
|
+
*
|
|
235
|
+
* The user also has the option to create and configure the document client outside of this code
|
|
236
|
+
* and use the {@link DynamoDbClient.from} method wrap it with a fresh instance of this class.
|
|
237
|
+
*
|
|
238
|
+
* @param params - The creation parameters.
|
|
239
|
+
*
|
|
240
|
+
* @returns A new instance of the {@link DynamoDbClient}.
|
|
241
|
+
*/
|
|
168
242
|
static create(params) {
|
|
169
|
-
const
|
|
170
|
-
const
|
|
171
|
-
|
|
243
|
+
const p = params || {};
|
|
244
|
+
const { logger } = p;
|
|
245
|
+
const dynamodb = new client_dynamodb_1.DynamoDBClient(p.dynamodb || {});
|
|
246
|
+
const client = lib_dynamodb_1.DynamoDBDocumentClient.from(dynamodb, p.document);
|
|
247
|
+
return DynamoDbClient.from({ client, logger });
|
|
172
248
|
}
|
|
173
249
|
}
|
|
174
250
|
exports.DynamoDbClient = DynamoDbClient;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/client.ts"],"names":[],"mappings":";;;AACA,
|
|
1
|
+
{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/client.ts"],"names":[],"mappings":"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"}
|
package/lib/esm/src/client.d.ts
CHANGED
|
@@ -1,15 +1,43 @@
|
|
|
1
1
|
import type { DynamoDBClientConfig } from "@aws-sdk/client-dynamodb";
|
|
2
|
-
import { DynamoDBClient as BaseClient } from "@aws-sdk/client-dynamodb";
|
|
3
2
|
import type { TranslateConfig } from "@aws-sdk/lib-dynamodb";
|
|
4
|
-
import { DynamoDBDocumentClient
|
|
3
|
+
import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
|
|
5
4
|
import type { Logger } from "@infra-blocks/logger-interface";
|
|
6
5
|
import { type Retry, type RetryConfig } from "@infra-blocks/retry";
|
|
7
6
|
import type { Attributes, GetItem, PutItem, Query, WriteTransaction } from "./types.js";
|
|
7
|
+
/**
|
|
8
|
+
* Creation parameters for the {@link DynamoDbClient}.
|
|
9
|
+
*/
|
|
10
|
+
export type CreateParams = {
|
|
11
|
+
/**
|
|
12
|
+
* The configuration for the vanilly DynamoDB client.
|
|
13
|
+
*
|
|
14
|
+
* When none is provided, the client is instantiated with the default configuration
|
|
15
|
+
* provided by the AWS SDK.
|
|
16
|
+
*/
|
|
17
|
+
dynamodb?: DynamoDBClientConfig;
|
|
18
|
+
/**
|
|
19
|
+
* The configuration for the document client.
|
|
20
|
+
*
|
|
21
|
+
* When none is provided, the document client is instantiated with the default
|
|
22
|
+
* configuration provided by the AWS SDK.
|
|
23
|
+
*/
|
|
24
|
+
document?: TranslateConfig;
|
|
25
|
+
/**
|
|
26
|
+
* Optional logger to use for logging.
|
|
27
|
+
*
|
|
28
|
+
* When none is provided, a {@link NullLogger} is used, which logs into the void.
|
|
29
|
+
*/
|
|
30
|
+
logger?: Logger;
|
|
31
|
+
};
|
|
8
32
|
export declare class DynamoDbClientError extends Error {
|
|
9
33
|
constructor(message: string, options?: {
|
|
10
34
|
cause?: unknown;
|
|
11
35
|
});
|
|
12
36
|
}
|
|
37
|
+
/**
|
|
38
|
+
* Wrapper class around the {@link DynamoDBDocumentClient} that provides added functionality,
|
|
39
|
+
* safer types and some convenience methods.
|
|
40
|
+
*/
|
|
13
41
|
export declare class DynamoDbClient {
|
|
14
42
|
private readonly client;
|
|
15
43
|
private readonly logger;
|
|
@@ -36,22 +64,95 @@ export declare class DynamoDbClient {
|
|
|
36
64
|
* @see https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html
|
|
37
65
|
*/
|
|
38
66
|
getItem<T>(params: GetItem): Promise<T | undefined>;
|
|
67
|
+
/**
|
|
68
|
+
* Puts an item using the PutItem API.
|
|
69
|
+
*
|
|
70
|
+
* Refer to the API documentation for more details on how it works. Basically, without
|
|
71
|
+
* conditions, this function will either insert a new document or *replace* the existing
|
|
72
|
+
* one with whatever attributes are provided.
|
|
73
|
+
*
|
|
74
|
+
* @param params - The parameters to use to put the item.
|
|
75
|
+
*
|
|
76
|
+
* @see https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html
|
|
77
|
+
*/
|
|
39
78
|
putItem(params: PutItem): Promise<void>;
|
|
79
|
+
/**
|
|
80
|
+
* Queries a table, or an index, using the Query API.
|
|
81
|
+
*
|
|
82
|
+
* Pagination is automatically handled as an async generator, yielding
|
|
83
|
+
* one item at a time.
|
|
84
|
+
*
|
|
85
|
+
* @param params - The parameters to use to query the table or index.
|
|
86
|
+
*
|
|
87
|
+
* @returns An async generator that yields items matching the query, one
|
|
88
|
+
* at a time, and that handles pagination automatically.
|
|
89
|
+
*
|
|
90
|
+
* @see https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html
|
|
91
|
+
*/
|
|
92
|
+
query<T extends Attributes = Attributes>(params: Query): AsyncGenerator<T>;
|
|
93
|
+
/**
|
|
94
|
+
* Convenience method over the {@link query} method enforcing that the query
|
|
95
|
+
* matches at most one item.
|
|
96
|
+
*
|
|
97
|
+
* If the query doesn't match any item, then `undefined` is returned. If there are
|
|
98
|
+
* matches, then the function throws as soon as a second matching item is returned.
|
|
99
|
+
*
|
|
100
|
+
* @param params - The parameters to use to query the table or index.
|
|
101
|
+
*
|
|
102
|
+
* @returns The only item matching the query, or `undefined` if no item matches.
|
|
103
|
+
*/
|
|
104
|
+
queryOne<T extends Attributes = Attributes>(params: Query): Promise<T | undefined>;
|
|
105
|
+
/**
|
|
106
|
+
* Executes a write transaction using the TransactWriteItems API.
|
|
107
|
+
*
|
|
108
|
+
* @param params - The parameters describing the transaction.
|
|
109
|
+
*
|
|
110
|
+
* @see https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html
|
|
111
|
+
*/
|
|
40
112
|
transactWriteItems(params: WriteTransaction): Promise<void>;
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
113
|
+
/**
|
|
114
|
+
* Alias for the {@link putItem} method.
|
|
115
|
+
*/
|
|
116
|
+
upsert: (params: PutItem) => Promise<void>;
|
|
117
|
+
/**
|
|
118
|
+
* Creates an instance of the {@link DynamoDbClient} wrapping the provided document
|
|
119
|
+
* client directly.
|
|
120
|
+
*
|
|
121
|
+
* This is useful when the user has already created a document client, or when the document
|
|
122
|
+
* client is a mock for testing purposes. Otherwise, {@link DynamoDbClient.create} should be
|
|
123
|
+
* preferred.
|
|
124
|
+
*
|
|
125
|
+
* @param params - The creation parameters.
|
|
126
|
+
*
|
|
127
|
+
* @returns A new instance of the {@link DynamoDbClient} wrapping the provided document client.
|
|
128
|
+
*/
|
|
48
129
|
static from(params: {
|
|
49
|
-
client:
|
|
50
|
-
logger?: Logger;
|
|
51
|
-
}): DynamoDbClient;
|
|
52
|
-
static create(params?: {
|
|
53
|
-
base?: DynamoDBClientConfig;
|
|
54
|
-
document?: TranslateConfig;
|
|
130
|
+
client: DynamoDBDocumentClient;
|
|
55
131
|
logger?: Logger;
|
|
56
132
|
}): DynamoDbClient;
|
|
133
|
+
/**
|
|
134
|
+
* Creates an instance of the {@link DynamoDbClient} using the provided parameters.
|
|
135
|
+
*
|
|
136
|
+
* The client is a wrapper around the {@link DynamoDBDocumentClient} from the `@aws-sdk/lib-dynamodb`
|
|
137
|
+
* package, which is itself a wrapper around the {@link DynamoDBClient} from the
|
|
138
|
+
* `@aws-sdk/client-dynamodb` package.
|
|
139
|
+
*
|
|
140
|
+
* This factory function first intantiates the vanilla client with optionally provided
|
|
141
|
+
* configuration, then wraps it in a {@link DynamoDBDocumentClient} that can also
|
|
142
|
+
* be configured. When no configuration is used, both clients are created using their
|
|
143
|
+
* respective default configuration.
|
|
144
|
+
*
|
|
145
|
+
* The DynamoDB vanilla client can be configured using the `dynamodb` parameter,
|
|
146
|
+
* The document client can be configured using the `document` parameter,
|
|
147
|
+
*
|
|
148
|
+
* The `logger` parameter is optional and defaults to a {@link NullLogger}.
|
|
149
|
+
*
|
|
150
|
+
* The user also has the option to create and configure the document client outside of this code
|
|
151
|
+
* and use the {@link DynamoDbClient.from} method wrap it with a fresh instance of this class.
|
|
152
|
+
*
|
|
153
|
+
* @param params - The creation parameters.
|
|
154
|
+
*
|
|
155
|
+
* @returns A new instance of the {@link DynamoDbClient}.
|
|
156
|
+
*/
|
|
157
|
+
static create(params?: CreateParams): DynamoDbClient;
|
|
57
158
|
}
|
package/lib/esm/src/client.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { DynamoDBClient
|
|
2
|
-
import { DynamoDBDocumentClient
|
|
1
|
+
import { DynamoDBClient, ListTablesCommand } from "@aws-sdk/client-dynamodb";
|
|
2
|
+
import { DynamoDBDocumentClient, GetCommand, PutCommand, QueryCommand, TransactWriteCommand, } from "@aws-sdk/lib-dynamodb";
|
|
3
3
|
import { NullLogger } from "@infra-blocks/null-logger";
|
|
4
4
|
import { retry } from "@infra-blocks/retry";
|
|
5
5
|
export class DynamoDbClientError extends Error {
|
|
@@ -8,13 +8,10 @@ export class DynamoDbClientError extends Error {
|
|
|
8
8
|
this.name = "DynamoDbClientError";
|
|
9
9
|
}
|
|
10
10
|
}
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
This is to say, we can create items in a different table that only has a pk for this specific use case, or we could
|
|
16
|
-
also use the same table. It's just going to add some sheeet to the table.
|
|
17
|
-
*/
|
|
11
|
+
/**
|
|
12
|
+
* Wrapper class around the {@link DynamoDBDocumentClient} that provides added functionality,
|
|
13
|
+
* safer types and some convenience methods.
|
|
14
|
+
*/
|
|
18
15
|
export class DynamoDbClient {
|
|
19
16
|
client;
|
|
20
17
|
logger;
|
|
@@ -77,6 +74,17 @@ export class DynamoDbClient {
|
|
|
77
74
|
});
|
|
78
75
|
}
|
|
79
76
|
}
|
|
77
|
+
/**
|
|
78
|
+
* Puts an item using the PutItem API.
|
|
79
|
+
*
|
|
80
|
+
* Refer to the API documentation for more details on how it works. Basically, without
|
|
81
|
+
* conditions, this function will either insert a new document or *replace* the existing
|
|
82
|
+
* one with whatever attributes are provided.
|
|
83
|
+
*
|
|
84
|
+
* @param params - The parameters to use to put the item.
|
|
85
|
+
*
|
|
86
|
+
* @see https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html
|
|
87
|
+
*/
|
|
80
88
|
async putItem(params) {
|
|
81
89
|
try {
|
|
82
90
|
await this.client.send(toPutCommand(params));
|
|
@@ -88,27 +96,25 @@ export class DynamoDbClient {
|
|
|
88
96
|
});
|
|
89
97
|
}
|
|
90
98
|
}
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
}
|
|
106
|
-
async *query(query) {
|
|
99
|
+
/**
|
|
100
|
+
* Queries a table, or an index, using the Query API.
|
|
101
|
+
*
|
|
102
|
+
* Pagination is automatically handled as an async generator, yielding
|
|
103
|
+
* one item at a time.
|
|
104
|
+
*
|
|
105
|
+
* @param params - The parameters to use to query the table or index.
|
|
106
|
+
*
|
|
107
|
+
* @returns An async generator that yields items matching the query, one
|
|
108
|
+
* at a time, and that handles pagination automatically.
|
|
109
|
+
*
|
|
110
|
+
* @see https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html
|
|
111
|
+
*/
|
|
112
|
+
async *query(params) {
|
|
107
113
|
try {
|
|
108
|
-
const { expression, attributeValues } =
|
|
114
|
+
const { expression, attributeValues } = params.condition.toJson();
|
|
109
115
|
let response = await this.client.send(new QueryCommand({
|
|
110
|
-
TableName:
|
|
111
|
-
IndexName:
|
|
116
|
+
TableName: params.table,
|
|
117
|
+
IndexName: params.index,
|
|
112
118
|
KeyConditionExpression: expression,
|
|
113
119
|
ExpressionAttributeValues: attributeValues,
|
|
114
120
|
}));
|
|
@@ -117,8 +123,8 @@ export class DynamoDbClient {
|
|
|
117
123
|
}
|
|
118
124
|
while (response.LastEvaluatedKey != null) {
|
|
119
125
|
response = await this.client.send(new QueryCommand({
|
|
120
|
-
TableName:
|
|
121
|
-
IndexName:
|
|
126
|
+
TableName: params.table,
|
|
127
|
+
IndexName: params.index,
|
|
122
128
|
KeyConditionExpression: expression,
|
|
123
129
|
ExpressionAttributeValues: attributeValues,
|
|
124
130
|
ExclusiveStartKey: response.LastEvaluatedKey,
|
|
@@ -129,15 +135,26 @@ export class DynamoDbClient {
|
|
|
129
135
|
}
|
|
130
136
|
}
|
|
131
137
|
catch (err) {
|
|
132
|
-
throw new DynamoDbClientError(
|
|
138
|
+
throw new DynamoDbClientError(`error while querying DynamoDB on table ${params.table}${params.index != null ? ` and index ${params.index}` : ""}`, {
|
|
133
139
|
cause: err,
|
|
134
140
|
});
|
|
135
141
|
}
|
|
136
142
|
}
|
|
137
|
-
|
|
143
|
+
/**
|
|
144
|
+
* Convenience method over the {@link query} method enforcing that the query
|
|
145
|
+
* matches at most one item.
|
|
146
|
+
*
|
|
147
|
+
* If the query doesn't match any item, then `undefined` is returned. If there are
|
|
148
|
+
* matches, then the function throws as soon as a second matching item is returned.
|
|
149
|
+
*
|
|
150
|
+
* @param params - The parameters to use to query the table or index.
|
|
151
|
+
*
|
|
152
|
+
* @returns The only item matching the query, or `undefined` if no item matches.
|
|
153
|
+
*/
|
|
154
|
+
async queryOne(params) {
|
|
138
155
|
try {
|
|
139
156
|
let item;
|
|
140
|
-
for await (const queryItem of this.query(
|
|
157
|
+
for await (const queryItem of this.query(params)) {
|
|
141
158
|
if (item != null) {
|
|
142
159
|
throw new DynamoDbClientError("expected one item in query but found at least 2");
|
|
143
160
|
}
|
|
@@ -147,24 +164,83 @@ export class DynamoDbClient {
|
|
|
147
164
|
}
|
|
148
165
|
catch (err) {
|
|
149
166
|
// TODO: careful here as email is PII.
|
|
150
|
-
throw new DynamoDbClientError(`error while querying one: ${JSON.stringify(
|
|
167
|
+
throw new DynamoDbClientError(`error while querying one: ${JSON.stringify(params)}`, {
|
|
151
168
|
cause: err,
|
|
152
169
|
});
|
|
153
170
|
}
|
|
154
171
|
}
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
172
|
+
/**
|
|
173
|
+
* Executes a write transaction using the TransactWriteItems API.
|
|
174
|
+
*
|
|
175
|
+
* @param params - The parameters describing the transaction.
|
|
176
|
+
*
|
|
177
|
+
* @see https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html
|
|
178
|
+
*/
|
|
179
|
+
async transactWriteItems(params) {
|
|
180
|
+
try {
|
|
181
|
+
const commandInput = toTransactWriteItemsCommandInput(params);
|
|
182
|
+
if (this.logger.isDebugEnabled()) {
|
|
183
|
+
this.logger.debug("executing transaction write: %s", JSON.stringify(commandInput));
|
|
184
|
+
}
|
|
185
|
+
const command = new TransactWriteCommand(commandInput);
|
|
186
|
+
await this.client.send(command);
|
|
187
|
+
}
|
|
188
|
+
catch (err) {
|
|
189
|
+
throw new DynamoDbClientError("error while transactionally writing items in DynamoDB", {
|
|
190
|
+
cause: err,
|
|
191
|
+
});
|
|
192
|
+
}
|
|
159
193
|
}
|
|
194
|
+
/**
|
|
195
|
+
* Alias for the {@link putItem} method.
|
|
196
|
+
*/
|
|
197
|
+
upsert = this.putItem;
|
|
198
|
+
/**
|
|
199
|
+
* Creates an instance of the {@link DynamoDbClient} wrapping the provided document
|
|
200
|
+
* client directly.
|
|
201
|
+
*
|
|
202
|
+
* This is useful when the user has already created a document client, or when the document
|
|
203
|
+
* client is a mock for testing purposes. Otherwise, {@link DynamoDbClient.create} should be
|
|
204
|
+
* preferred.
|
|
205
|
+
*
|
|
206
|
+
* @param params - The creation parameters.
|
|
207
|
+
*
|
|
208
|
+
* @returns A new instance of the {@link DynamoDbClient} wrapping the provided document client.
|
|
209
|
+
*/
|
|
160
210
|
static from(params) {
|
|
161
211
|
const { client, logger = NullLogger.create() } = params;
|
|
162
212
|
return new DynamoDbClient({ client, logger });
|
|
163
213
|
}
|
|
214
|
+
/**
|
|
215
|
+
* Creates an instance of the {@link DynamoDbClient} using the provided parameters.
|
|
216
|
+
*
|
|
217
|
+
* The client is a wrapper around the {@link DynamoDBDocumentClient} from the `@aws-sdk/lib-dynamodb`
|
|
218
|
+
* package, which is itself a wrapper around the {@link DynamoDBClient} from the
|
|
219
|
+
* `@aws-sdk/client-dynamodb` package.
|
|
220
|
+
*
|
|
221
|
+
* This factory function first intantiates the vanilla client with optionally provided
|
|
222
|
+
* configuration, then wraps it in a {@link DynamoDBDocumentClient} that can also
|
|
223
|
+
* be configured. When no configuration is used, both clients are created using their
|
|
224
|
+
* respective default configuration.
|
|
225
|
+
*
|
|
226
|
+
* The DynamoDB vanilla client can be configured using the `dynamodb` parameter,
|
|
227
|
+
* The document client can be configured using the `document` parameter,
|
|
228
|
+
*
|
|
229
|
+
* The `logger` parameter is optional and defaults to a {@link NullLogger}.
|
|
230
|
+
*
|
|
231
|
+
* The user also has the option to create and configure the document client outside of this code
|
|
232
|
+
* and use the {@link DynamoDbClient.from} method wrap it with a fresh instance of this class.
|
|
233
|
+
*
|
|
234
|
+
* @param params - The creation parameters.
|
|
235
|
+
*
|
|
236
|
+
* @returns A new instance of the {@link DynamoDbClient}.
|
|
237
|
+
*/
|
|
164
238
|
static create(params) {
|
|
165
|
-
const
|
|
166
|
-
const
|
|
167
|
-
|
|
239
|
+
const p = params || {};
|
|
240
|
+
const { logger } = p;
|
|
241
|
+
const dynamodb = new DynamoDBClient(p.dynamodb || {});
|
|
242
|
+
const client = DynamoDBDocumentClient.from(dynamodb, p.document);
|
|
243
|
+
return DynamoDbClient.from({ client, logger });
|
|
168
244
|
}
|
|
169
245
|
}
|
|
170
246
|
// Could be associated on the PutItem type if it was an opaque type rather
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/client.ts"],"names":[],"mappings":"AACA,OAAO,
|
|
1
|
+
{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAM7E,OAAO,EACL,sBAAsB,EACtB,UAAU,EACV,UAAU,EACV,YAAY,EACZ,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAgC,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAmC1E,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,cAAc;IACR,MAAM,CAAyB;IAC/B,MAAM,CAAS;IAEhC,YAAoB,MAGnB;QACC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;QAClC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,OAA+C;QACnD,OAAO,KAAK,CACV,KAAK,IAAI,EAAE;YACT,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,iBAAiB,CAAC,EAAE,CAAC,CAAC,CAAC;QACpD,CAAC,EACD;YACE,GAAG,OAAO;YACV,gBAAgB,EAAE,CAAC,GAAU,EAAE,EAAE;gBAC/B,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;oBAClB,OAAO,GAAG,CAAC,IAAI,KAAK,YAAY,CAAC;gBACnC,CAAC;gBACD,OAAO,KAAK,CAAC;YACf,CAAC;SACF,CACF,CAAC;IACJ,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,OAAO,CAAI,MAAe;QAC9B,IAAI,CAAC;YACH,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;YACjD,MAAM,GAAG,GAAG;gBACV,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,KAAK;aAC1C,CAAC;YACF,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;gBACpB,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC;YACpC,CAAC;YAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CACrC,IAAI,UAAU,CAAC;gBACb,SAAS,EAAE,KAAK;gBAChB,GAAG,EAAE,GAAG;aACT,CAAC,CACH,CAAC;YAEF,OAAO,QAAQ,CAAC,IAAqB,CAAC;QACxC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,mBAAmB,CAC3B,2CAA2C,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,EACnE;gBACE,KAAK,EAAE,GAAG;aACX,CACF,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,OAAO,CAAC,MAAe;QAC3B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;QAC/C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,mDAAmD,EACnD,GAAG,CACJ,CAAC;YACF,MAAM,IAAI,mBAAmB,CAAC,sCAAsC,EAAE;gBACpE,KAAK,EAAE,GAAG;aACX,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,CAAC,KAAK,CACV,MAAa;QAEb,IAAI,CAAC;YACH,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;YAClE,IAAI,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CACnC,IAAI,YAAY,CAAC;gBACf,SAAS,EAAE,MAAM,CAAC,KAAK;gBACvB,SAAS,EAAE,MAAM,CAAC,KAAK;gBACvB,sBAAsB,EAAE,UAAU;gBAClC,yBAAyB,EAAE,eAAe;aAC3C,CAAC,CACH,CAAC;YAEF,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;gBACxC,MAAM,IAAS,CAAC;YAClB,CAAC;YAED,OAAO,QAAQ,CAAC,gBAAgB,IAAI,IAAI,EAAE,CAAC;gBACzC,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAC/B,IAAI,YAAY,CAAC;oBACf,SAAS,EAAE,MAAM,CAAC,KAAK;oBACvB,SAAS,EAAE,MAAM,CAAC,KAAK;oBACvB,sBAAsB,EAAE,UAAU;oBAClC,yBAAyB,EAAE,eAAe;oBAC1C,iBAAiB,EAAE,QAAQ,CAAC,gBAAgB;iBAC7C,CAAC,CACH,CAAC;gBAEF,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;oBACxC,MAAM,IAAS,CAAC;gBAClB,CAAC;YACH,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,mBAAmB,CAC3B,0CAA0C,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,cAAc,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EACnH;gBACE,KAAK,EAAE,GAAG;aACX,CACF,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,QAAQ,CACZ,MAAa;QAEb,IAAI,CAAC;YACH,IAAI,IAAmB,CAAC;YACxB,IAAI,KAAK,EAAE,MAAM,SAAS,IAAI,IAAI,CAAC,KAAK,CAAI,MAAM,CAAC,EAAE,CAAC;gBACpD,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;oBACjB,MAAM,IAAI,mBAAmB,CAC3B,iDAAiD,CAClD,CAAC;gBACJ,CAAC;gBACD,IAAI,GAAG,SAAS,CAAC;YACnB,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,sCAAsC;YACtC,MAAM,IAAI,mBAAmB,CAC3B,6BAA6B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,EACrD;gBACE,KAAK,EAAE,GAAG;aACX,CACF,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,kBAAkB,CAAC,MAAwB;QAC/C,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,gCAAgC,CAAC,MAAM,CAAC,CAAC;YAC9D,IAAI,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,EAAE,CAAC;gBACjC,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,iCAAiC,EACjC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,CAC7B,CAAC;YACJ,CAAC;YACD,MAAM,OAAO,GAAG,IAAI,oBAAoB,CAAC,YAAY,CAAC,CAAC;YACvD,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAClC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,mBAAmB,CAC3B,uDAAuD,EACvD;gBACE,KAAK,EAAE,GAAG;aACX,CACF,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;OAEG;IACH,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC;IAEtB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,IAAI,CAAC,MAGX;QACC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,EAAE,GAAG,MAAM,CAAC;QACxD,OAAO,IAAI,cAAc,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAChD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,CAAC,MAAM,CAAC,MAAqB;QACjC,MAAM,CAAC,GAAG,MAAM,IAAI,EAAE,CAAC;QACvB,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;QACrB,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;QACtD,MAAM,MAAM,GAAG,sBAAsB,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC;QACjE,OAAO,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACjD,CAAC;CACF;AAED,0EAA0E;AAC1E,qBAAqB;AACrB,SAAS,YAAY,CAAC,MAAe;IACnC,OAAO,IAAI,UAAU,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,mBAAmB,CAAC,MAAe;IAC1C,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;IAC1C,MAAM,gBAAgB,GAAG,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACzE,OAAO;QACL,SAAS,EAAE,KAAK;QAChB,IAAI,EAAE,IAAI;QACV,GAAG,gBAAgB;KACpB,CAAC;AACJ,CAAC;AAED,SAAS,gCAAgC,CACvC,MAAwB;IAExB,OAAO;QACL,aAAa,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACzC,GAAG,EAAE,mBAAmB,CAAC,IAAI,CAAC;SAC/B,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC"}
|