From ba0c2e324ae40d9f8ffad6b12db6329059a01766 Mon Sep 17 00:00:00 2001
From: wingbot <109207340+monadabot@users.noreply.github.com>
Date: Fri, 6 Oct 2023 01:32:14 +0300
Subject: [PATCH] feat(docs): update docs (#641)
feat(docs): update docs
Updates the Wing docs. See details in [workflow run].
[Workflow Run]: https://github.com/winglang/docsite/actions/runs/6425130943
------
*Automatically created via the "update-docs" workflow*
---
.../02-ex/dynamodb-table.md | 275 +++++++++++++++++-
versioned_docs/version-latest/05-libraries.md | 72 +++++
.../version-latest/06-tools/01-cli.md | 14 +
3 files changed, 357 insertions(+), 4 deletions(-)
create mode 100644 versioned_docs/version-latest/05-libraries.md
diff --git a/versioned_docs/version-latest/04-standard-library/02-ex/dynamodb-table.md b/versioned_docs/version-latest/04-standard-library/02-ex/dynamodb-table.md
index 6c393c397..d8597c58c 100644
--- a/versioned_docs/version-latest/04-standard-library/02-ex/dynamodb-table.md
+++ b/versioned_docs/version-latest/04-standard-library/02-ex/dynamodb-table.md
@@ -46,6 +46,7 @@ new ex.DynamodbTable(props: DynamodbTableProps);
| putItem | Put an item into the table. |
| query | Return all items with a given partition key value. |
| scan | Return one or more items and item attributes by accessing every item in a table or a secondary index. |
+| transactGetItems | Perform a synchronous read operation that groups up to 100 item retrievals. |
| transactWriteItems | Perform a synchronous write operation that groups up to 100 action requests. |
| updateItem | Get an item from the table. |
@@ -59,6 +60,8 @@ inflight batchGetItem(options: DynamodbTableBatchGetItemOptions): DynamodbTableB
Return the attributes of one or more items.
+> [https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchGetItem.html](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchGetItem.html)
+
###### `options`Required
- *Type:* DynamodbTableBatchGetItemOptions
@@ -75,6 +78,8 @@ inflight batchWriteItem(options: DynamodbTableBatchWriteItemOptions): DynamodbTa
Put or delete multiple items.
+> [https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html)
+
###### `options`Required
- *Type:* DynamodbTableBatchWriteItemOptions
@@ -91,6 +96,8 @@ inflight deleteItem(options: DynamodbTableDeleteItemOptions): DynamodbTableDelet
Delete an item from the table.
+> [https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DeleteItem.html](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DeleteItem.html)
+
###### `options`Required
- *Type:* DynamodbTableDeleteItemOptions
@@ -107,6 +114,8 @@ inflight getItem(options: DynamodbTableGetItemOptions): DynamodbTableGetItemResu
Get an item from the table.
+> [https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html)
+
###### `options`Required
- *Type:* DynamodbTableGetItemOptions
@@ -123,6 +132,8 @@ inflight putItem(options: DynamodbTablePutItemOptions): DynamodbTablePutItemResu
Put an item into the table.
+> [https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html)
+
###### `options`Required
- *Type:* DynamodbTablePutItemOptions
@@ -139,6 +150,8 @@ inflight query(options: DynamodbTableQueryOptions): DynamodbTableQueryResult
Return all items with a given partition key value.
+> [https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html)
+
###### `options`Required
- *Type:* DynamodbTableQueryOptions
@@ -155,6 +168,8 @@ inflight scan(options?: DynamodbTableScanOptions): DynamodbTableScanResult
Return one or more items and item attributes by accessing every item in a table or a secondary index.
+> [https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Scan.html](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Scan.html)
+
###### `options`Optional
- *Type:* DynamodbTableScanOptions
@@ -163,6 +178,24 @@ options for the scan operation.
---
+##### `transactGetItems`
+
+```wing
+inflight transactGetItems(options: DynamodbTransactGetItemsOptions): DynamodbTableTransactGetItemsResult
+```
+
+Perform a synchronous read operation that groups up to 100 item retrievals.
+
+> [https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactGetItems.html](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactGetItems.html)
+
+###### `options`Required
+
+- *Type:* DynamodbTransactGetItemsOptions
+
+options for the query operation.
+
+---
+
##### `transactWriteItems`
```wing
@@ -171,6 +204,8 @@ inflight transactWriteItems(options: DynamodbTransactWriteItemsOptions): Dynamod
Perform a synchronous write operation that groups up to 100 action requests.
+> [https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html)
+
###### `options`Required
- *Type:* DynamodbTransactWriteItemsOptions
@@ -187,6 +222,8 @@ inflight updateItem(options: DynamodbTableUpdateItemOptions): DynamodbTableUpdat
Get an item from the table.
+> [https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html)
+
###### `options`Required
- *Type:* DynamodbTableUpdateItemOptions
@@ -271,6 +308,7 @@ the table name.
| putItem | Put an item into the table. |
| query | Return all items with a given partition key value. |
| scan | Return one or more items and item attributes by accessing every item in a table or a secondary index. |
+| transactGetItems | Perform a synchronous read operation that groups up to 100 item retrievals. |
| transactWriteItems | Perform a synchronous write operation that groups up to 100 action requests. |
| updateItem | Get an item from the table. |
@@ -374,6 +412,20 @@ Return one or more items and item attributes by accessing every item in a table
---
+##### `transactGetItems`
+
+```wing
+transactGetItems(options: DynamodbTransactGetItemsOptions): DynamodbTableTransactGetItemsResult
+```
+
+Perform a synchronous read operation that groups up to 100 item retrievals.
+
+###### `options`Required
+
+- *Type:* DynamodbTransactGetItemsOptions
+
+---
+
##### `transactWriteItems`
```wing
@@ -691,7 +743,7 @@ let DynamodbTableBatchWriteItemPutRequestOptions = ex.DynamodbTableBatchWriteIte
| **Name** | **Type** | **Description** |
| --- | --- | --- |
-| item | Json | A map of attribute name to attribute values, representing the primary key of an item to be processed by `PutItem`. |
+| item | Json | The values of the item to be put. |
---
@@ -703,7 +755,7 @@ item: Json;
- *Type:* Json
-A map of attribute name to attribute values, representing the primary key of an item to be processed by `PutItem`.
+The values of the item to be put.
---
@@ -1902,6 +1954,83 @@ The primary key of the item where the operation stopped, inclusive of the previo
---
+### DynamodbTableTransactGetItemsResponseItem
+
+Details of the requested item.
+
+#### Initializer
+
+```wing
+bring ex;
+
+let DynamodbTableTransactGetItemsResponseItem = ex.DynamodbTableTransactGetItemsResponseItem{ ... };
+```
+
+#### Properties
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| item | Json | The values of the item. |
+
+---
+
+##### `item`Required
+
+```wing
+item: Json;
+```
+
+- *Type:* Json
+
+The values of the item.
+
+---
+
+### DynamodbTableTransactGetItemsResult
+
+Result for `DynamodbTable.transactGetItems`.
+
+#### Initializer
+
+```wing
+bring ex;
+
+let DynamodbTableTransactGetItemsResult = ex.DynamodbTableTransactGetItemsResult{ ... };
+```
+
+#### Properties
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| responses | MutArray<DynamodbTableTransactGetItemsResponseItem> | An ordered array of up to 100 `DynamodbTableTransactGetItemsResponseItem` objects. |
+| consumedCapacity | Json | The capacity units consumed by the operation. |
+
+---
+
+##### `responses`Required
+
+```wing
+responses: MutArray;
+```
+
+- *Type:* MutArray<DynamodbTableTransactGetItemsResponseItem>
+
+An ordered array of up to 100 `DynamodbTableTransactGetItemsResponseItem` objects.
+
+---
+
+##### `consumedCapacity`Optional
+
+```wing
+consumedCapacity: Json;
+```
+
+- *Type:* Json
+
+The capacity units consumed by the operation.
+
+---
+
### DynamodbTableTransactWriteItemsResult
Result for `DynamodbTable.transactWriteItems`.
@@ -2158,6 +2287,144 @@ Information about item collections, if any, that were affected by the operation.
---
+### DynamodbTransactGetItem
+
+Dynamodb transact get operation.
+
+#### Initializer
+
+```wing
+bring ex;
+
+let DynamodbTransactGetItem = ex.DynamodbTransactGetItem{ ... };
+```
+
+#### Properties
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| get | DynamodbTransactGetItemGetProps | A request to perform a get operation. |
+
+---
+
+##### `get`Optional
+
+```wing
+get: DynamodbTransactGetItemGetProps;
+```
+
+- *Type:* DynamodbTransactGetItemGetProps
+
+A request to perform a get operation.
+
+---
+
+### DynamodbTransactGetItemGetProps
+
+Options for `DynamodbTable.transactGetItems`'s get operation.
+
+#### Initializer
+
+```wing
+bring ex;
+
+let DynamodbTransactGetItemGetProps = ex.DynamodbTransactGetItemGetProps{ ... };
+```
+
+#### Properties
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| key | Json | The primary key of the item to be retrieved. |
+| expressionAttributeNames | Json | One or more substitution tokens for attribute names in an expression. |
+| projectionExpression | str | A string that identifies one or more attributes to retrieve from the table. |
+
+---
+
+##### `key`Required
+
+```wing
+key: Json;
+```
+
+- *Type:* Json
+
+The primary key of the item to be retrieved.
+
+---
+
+##### `expressionAttributeNames`Optional
+
+```wing
+expressionAttributeNames: Json;
+```
+
+- *Type:* Json
+- *Default:* undefined
+
+One or more substitution tokens for attribute names in an expression.
+
+---
+
+##### `projectionExpression`Optional
+
+```wing
+projectionExpression: str;
+```
+
+- *Type:* str
+- *Default:* undefined
+
+A string that identifies one or more attributes to retrieve from the table.
+
+---
+
+### DynamodbTransactGetItemsOptions
+
+Options for `DynamodbTable.transactGetItems`.
+
+#### Initializer
+
+```wing
+bring ex;
+
+let DynamodbTransactGetItemsOptions = ex.DynamodbTransactGetItemsOptions{ ... };
+```
+
+#### Properties
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| transactItems | MutArray<DynamodbTransactGetItem> | An ordered array of up to 100 `DynamodbTransactGetItem` objects, each of which contains a `DynamodbTransactGetItem` structure. |
+| returnConsumedCapacity | str | Determines the level of detail about either provisioned or on-demand throughput consumption. |
+
+---
+
+##### `transactItems`Required
+
+```wing
+transactItems: MutArray;
+```
+
+- *Type:* MutArray<DynamodbTransactGetItem>
+
+An ordered array of up to 100 `DynamodbTransactGetItem` objects, each of which contains a `DynamodbTransactGetItem` structure.
+
+---
+
+##### `returnConsumedCapacity`Optional
+
+```wing
+returnConsumedCapacity: str;
+```
+
+- *Type:* str
+- *Default:* "NONE"
+
+Determines the level of detail about either provisioned or on-demand throughput consumption.
+
+---
+
### DynamodbTransactWriteItem
Dynamodb transact write operation.
@@ -2415,7 +2682,7 @@ let DynamodbTransactWriteItemPutProps = ex.DynamodbTransactWriteItemPutProps{ ..
| **Name** | **Type** | **Description** |
| --- | --- | --- |
-| item | Json | The item to put. |
+| item | Json | The values of the item to be put. |
| conditionExpression | str | A condition that must be satisfied in order for the operation to succeed. |
---
@@ -2428,7 +2695,7 @@ item: Json;
- *Type:* Json
-The item to put.
+The values of the item to be put.
---
diff --git a/versioned_docs/version-latest/05-libraries.md b/versioned_docs/version-latest/05-libraries.md
new file mode 100644
index 000000000..28367cbbe
--- /dev/null
+++ b/versioned_docs/version-latest/05-libraries.md
@@ -0,0 +1,72 @@
+---
+title: Wing Libraries
+id: libraries
+description: Documentation about Wing libraries
+sidebar_label: Libraries
+keywords: [Wing reference, Wing libraries, libraries, packaging, packages]
+---
+
+As you write larger Wing applications, organizing your code becomes increasingly important.
+By grouping related functionality and separating code with distinct features, you'll make it easier to find code that implements a particular feature and where to go to change how a feature works.
+As the project grows further, you can extract parts into separate libraries that become external dependencies.
+
+Any Wing project can be packaged as a library, which will export all public types (like classes and structs) so that they can be used by multiple applications.
+
+> Note: today all types in libraries are public by default, but there is a planned breaking change to make types private by default. Follow for more information.
+
+Let's first start with how to consume a Wing library.
+
+## Using a Wing library
+
+Wing libraries can be installed using the npm command line tool.
+
+```
+npm i wing-redis
+```
+
+Then in your Wing source code, the library can be imported by name using a `bring` statement:
+
+```js
+bring "wing-redis" as redis;
+
+new redis.Redis();
+```
+
+Libraries can expose the following kinds of API elements:
+
+- Classes
+- Structs
+- Interfaces
+- Enums
+- Constants (coming soon - see https://github.com/winglang/wing/issues/3606 to track)
+
+APIs in libraries can also be organized hierarchically for better organization.
+For example, a library may split up its API elements between multiple modules (also sometimes called "namespaces"):
+
+```js
+bring "my-wing-payments-library" as payments;
+
+new payments.charges.Charge();
+new payments.customer.Customer();
+```
+
+### Creating a Wing library
+
+Packaging your own Wing code as a library is straightforward.
+Let's walk through it step by step.
+
+First, check that your project is organized based on how you want to structure your library.
+There are two main rules to be aware of:
+
+1. APIs can only be exported from non-entrypoint files (files that do not end in `.main.w` or `.test.w`).
+ Entrypoint files are perfect for writing tests and deployment scenarios that can be executed as-is - but if you have classes and other APIs you want to share, they have to be defined in non-entrypoint files (also known as module files).
+
+2. APIs are organized based on the project's directory structure.
+ If you want a group of classes to be part of a namespace named "storage", define them in a directory named "storage" (for example, some classes could be defined in `storage/file1.w`, several more in `storage/file2.w`, and so on).
+ All public APIs defined at the root of your project will be available at top-level namespace in your library.
+
+Next, run `npm init` to create a `package.json` file with information about your library.
+Make sure you fill out the "name", "version", "description", "author", and "license" fields.
+
+Finally, run `wing pack` at the root of your project directory.
+`wing pack` will compile your project and create a .tgz file that can be published to [npm](https://www.npmjs.com/), [GitHub Packages](https://github.com/features/packages), or any other Node.js package managing service.
diff --git a/versioned_docs/version-latest/06-tools/01-cli.md b/versioned_docs/version-latest/06-tools/01-cli.md
index 393420c9a..5c4b298ca 100644
--- a/versioned_docs/version-latest/06-tools/01-cli.md
+++ b/versioned_docs/version-latest/06-tools/01-cli.md
@@ -200,3 +200,17 @@ pass | test_bucket.w | root/test:put
```
We will see that both functions were invoked and that the tests passed.
+
+## Package: `wing pack`
+
+The `wing pack` command can be used to package your project as a Wing library.
+
+Usage:
+
+```sh
+$ wing pack
+```
+
+This will compile your current Wing directory, and bundle it as a tarball that can be published to [GitHub packages](https://github.com/features/packages) or [npm](https://www.npmjs.com/).
+
+See [Libraries](../05-libraries.md) for more details on packaging and consuming Wing libraries.