Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Renaming Document to Item #1152

Merged
merged 5 commits into from
Mar 21, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 2 additions & 0 deletions PENDING_CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ Please comment or [contact me](https://charlie.fish/contact) if you have any que
- `input` has changed to `convertToAttr`
- `output` has changed to `convertToNative`
- For more information please refer to the AWS-SDK v3 changelogs
- Renamed `Document` to `Item`
- The largest user facing API change is changing `{"return": "document"}` to `{"return": "item"}` and `{"return": "documents"}` to `{"return": "items"}`
- Node.js >=v10 now required

### Major New Features
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/getting_started/Introduction.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ Dynamoose is a modeling tool for Amazon's DynamoDB. Dynamoose is heavily inspire
- Type safety
- High level API
- Easy to use syntax
- Ability to transform data before saving or retrieving documents
- Ability to transform data before saving or retrieving items
- Strict data modeling (validation, required attributes, and more)
- Support for DynamoDB Transactions
- Powerful Conditional/Filtering Support
- Callback & Promise support
- Callback & Promise support
4 changes: 2 additions & 2 deletions docs/docs/getting_started/TypeScript.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,9 +38,9 @@ No. There is no differences between using Dynamoose with TypeScript and JavaScri

### What does TypeScript support mean? What typings are included?

TypeScript support includes support for all functions/methods, and properties of Dynamoose. It does **not** have typings or contracts between your Schema and Documents you create. All type checks between your Schema and Documents is handled at runtime as part of Dynamoose, and not part of the TypeScript typings.
TypeScript support includes support for all functions/methods, and properties of Dynamoose. It does **not** have typings or contracts between your Schema and Items you create. All type checks between your Schema and Items is handled at runtime as part of Dynamoose, and not part of the TypeScript typings.

At some point we hope to explore the potiental of adding typings to ensure your Documents conform to your Schemas. However this raises a lot of questions regarding if it's even possible to have such dynamic typings in TypeScript, as well as edge cases that have not been considered yet.
At some point we hope to explore the potiental of adding typings to ensure your Items conform to your Schemas. However this raises a lot of questions regarding if it's even possible to have such dynamic typings in TypeScript, as well as edge cases that have not been considered yet.

### What should I do if I have additional questions?

Expand Down
28 changes: 14 additions & 14 deletions docs/docs/guide/Condition.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ You will use this function with a comparison function which will complete the fi

```js
new dynamoose.Condition().filter("id"); // Currently this condition has no filter behavior and will represent an empty conditional
new dynamoose.Condition().filter("id").eq(1); // Since this condition has a comparison function (eq) after the filter it will complete the filter conditional and only represent documents where `id` = 1
new dynamoose.Condition().filter("id").eq(1); // Since this condition has a comparison function (eq) after the filter it will complete the filter conditional and only represent items where `id` = 1
```

## condition.where(key)
Expand All @@ -117,79 +117,79 @@ This function is identical to [`condition.filter(key)`](#conditionfilterkey) and
This comparison function will check to see if the given filter key is equal to the value you pass in as a parameter.

```js
new dynamoose.Condition().filter("name").eq("Tom"); // Condition all documents where `name` equals `Tom`
new dynamoose.Condition().filter("name").eq("Tom"); // Condition all items where `name` equals `Tom`
```

## condition.exists()

This comparison function will check to see if the given filter key exists in the document.
This comparison function will check to see if the given filter key exists in the item.

```js
new dynamoose.Condition().filter("phoneNumber").exists(); // Represents all documents where `phoneNumber` exists in the document
new dynamoose.Condition().filter("phoneNumber").exists(); // Represents all items where `phoneNumber` exists in the item

new dynamoose.Condition().filter("phoneNumber").not().exists(); // Represents all documents where `phoneNumber` does not exist in the document
new dynamoose.Condition().filter("phoneNumber").not().exists(); // Represents all items where `phoneNumber` does not exist in the item
```

## condition.lt(value)

This comparison function will check to see if the given filter key is less than the value you pass in as a parameter.

```js
new dynamoose.Condition().filter("age").lt(5); // Represents all documents where `age` is less than 5
new dynamoose.Condition().filter("age").lt(5); // Represents all items where `age` is less than 5
```

## condition.le(value)

This comparison function will check to see if the given filter key is less than or equal to the value you pass in as a parameter.

```js
new dynamoose.Condition().filter("age").le(5); // Represents all documents where `age` is less than or equal to 5
new dynamoose.Condition().filter("age").le(5); // Represents all items where `age` is less than or equal to 5
```

## condition.gt(value)

This comparison function will check to see if the given filter key is greater than the value you pass in as a parameter.

```js
new dynamoose.Condition().filter("age").gt(5); // Represents all documents where `age` is greater than 5
new dynamoose.Condition().filter("age").gt(5); // Represents all items where `age` is greater than 5
```

## condition.ge(value)

This comparison function will check to see if the given filter key is greater than or equal to the value you pass in as a parameter.

```js
new dynamoose.Condition().filter("age").ge(5); // Represents all documents where `age` is greater than or equal to 5
new dynamoose.Condition().filter("age").ge(5); // Represents all items where `age` is greater than or equal to 5
```

## condition.beginsWith(value)

This comparison function will check to see if the given filter key begins with the value you pass in as a parameter.

```js
new dynamoose.Condition().filter("name").beginsWith("T"); // Represents all documents where `name` begins with `T`
new dynamoose.Condition().filter("name").beginsWith("T"); // Represents all items where `name` begins with `T`
```

## condition.contains(value)

This comparison function will check to see if the given filter key contains the value you pass in as a parameter.

```js
new dynamoose.Condition().filter("name").contains("om"); // Represents all documents where `name` contains `om`
new dynamoose.Condition().filter("name").contains("om"); // Represents all items where `name` contains `om`
```

## condition.in(values)

This comparison function will check to see if the given filter key equals any of the documents you pass in in the values array you pass in. The `values` parameter must be an array and will only represent documents where the value for the given key exists in the array you pass in.
This comparison function will check to see if the given filter key equals any of the items you pass in in the values array you pass in. The `values` parameter must be an array and will only represent items where the value for the given key exists in the array you pass in.

```js
new dynamoose.Condition("name").in(["Charlie", "Bob"]) // Represents all documents where `name` = `Charlie` OR `Bob`
new dynamoose.Condition("name").in(["Charlie", "Bob"]) // Represents all items where `name` = `Charlie` OR `Bob`
```

## condition.between(a, b)

This comparison function will check to see if the given filter key is between the two values you pass in as parameters.

```js
new dynamoose.Condition().filter("age").between(5, 9); // Represents all documents where `age` is between 5 and 9
new dynamoose.Condition().filter("age").between(5, 9); // Represents all items where `age` is between 5 and 9
```
38 changes: 19 additions & 19 deletions docs/docs/guide/Document.md → docs/docs/guide/Item.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
A document represents an item for a given model in DynamoDB. This item can created locally (meaning it's not yet saved in DynamoDB), or created from an item already stored in DynamoDB (ex. `Model.get`).
The Dynamoose item represents an item for a given model in DynamoDB. This item can created locally (meaning it's not yet saved in DynamoDB), or created from an item already stored in DynamoDB (ex. `Model.get`).

A document/item is similar to a row in a relational database or a document in MongoDB.
A item is similar to a row in a relational database or a document in MongoDB.

## new Model(object)

In order to create a new document you just pass in your object into an instance of your model.
In order to create a new item you just pass in your object into an instance of your model.

```js
const User = dynamoose.model("User", {"id": Number, "name": String});
Expand All @@ -14,21 +14,21 @@ const myUser = new User({
});
console.log(myUser.id); // 1

// myUser is now a document instance of the User model
// myUser is now a item instance of the User model
```

## document.save([settings,] [callback])
## item.save([settings,] [callback])

This saves a document to DynamoDB. This method uses the `putItem` DynamoDB API call to store your object in the given table associated with the model. This method is overwriting, and will overwrite the data you currently have in place for the existing key for your table.
This saves a item to DynamoDB. This method uses the `putItem` DynamoDB API call to store your object in the given table associated with the model. This method is overwriting, and will overwrite the data you currently have in place for the existing key for your table.

This method returns a promise that will resolve when the operation is complete, this promise will reject upon failure. You can also pass in a function into the `callback` parameter to have it be used in a callback format as opposed to a promise format. Nothing will be passed into the result for the promise or callback.

You can also pass a settings object in as the first parameter. The following options are available for settings are:

| Name | Type | Default | Notes |
|---|---|---|---|
| overwrite | boolean | true | If an existing document with the same hash key should be overwritten in the database. You can set this to false to not overwrite an existing document with the same hash key. |
| return | string | `document` | If the function should return the `document` or `request`. If you set this to `request` the request that would be made to DynamoDB will be returned, but no requests will be made to DynamoDB. |
| overwrite | boolean | true | If an existing item with the same hash key should be overwritten in the database. You can set this to false to not overwrite an existing item with the same hash key. |
| return | string | `item` | If the function should return the `item` or `request`. If you set this to `request` the request that would be made to DynamoDB will be returned, but no requests will be made to DynamoDB. |
| condition | [`dynamoose.Condition`](Condition) | `null` | This is an optional instance of a Condition for the save. |

Both `settings` and `callback` parameters are optional. You can pass in a `callback` without `settings`, just by passing in one argument and having that argument be the `callback`. You are not required to pass in `settings` if you just want to pass in a `callback`.
Expand Down Expand Up @@ -58,9 +58,9 @@ myUser.save((error) => {
});
```

## document.delete([callback])
## item.delete([callback])

This deletes the given document from DynamoDB. This method uses the `deleteItem` DynamoDB API call to delete your object in the given table associated with the model.
This deletes the given item from DynamoDB. This method uses the `deleteItem` DynamoDB API call to delete your object in the given table associated with the model.

This method returns a promise that will resolve when the operation is complete, this promise will reject upon failure. You can also pass in a function into the `callback` parameter to have it be used in a callback format as opposed to a promise format. Nothing will be passed into the result for the promise or callback.

Expand All @@ -86,9 +86,9 @@ myUser.delete((error) => {
});
```

## document.populate([settings], [callback])
## item.populate([settings], [callback])

This allows you to populate a document with document instances for the subdocuments you are referencing in your schema. This function will return a promise, or call the `callback` paramter function upon completion.
This allows you to populate a item with item instances for the subitems you are referencing in your schema. This function will return a promise, or call the `callback` paramter function upon completion.

The `settings` parameter is an object you can pass in with the following properties:

Expand Down Expand Up @@ -117,9 +117,9 @@ user.populate((populatedUser, error) => {
});
```

## document.serialize([serializer])
## item.serialize([serializer])

This function serializes the document with the given serializer. The serializer parameter can either be a string or object. If it is an object you can pass in the same serializer as you do into [`Model.serializer.add`](Model#modelserializeraddname-serializer). If you pass in a string it will use the registered serializer with that name that is attached to the Model.
This function serializes the item with the given serializer. The serializer parameter can either be a string or object. If it is an object you can pass in the same serializer as you do into [`Model.serializer.add`](Model#modelserializeraddname-serializer). If you pass in a string it will use the registered serializer with that name that is attached to the Model.

This function will return an object.

Expand All @@ -140,7 +140,7 @@ const myUser = new User({"id": 1, "name": "Bob"});
myUser.serialize(); // {"id": 1, "name": "Bob"}
```

## document.original()
## item.original()

This function returns the original item that was received from DynamoDB. This function will return a JSON object that represents the original item. In the event no item has been retrieved from DynamoDB `null` will be returned.

Expand All @@ -153,18 +153,18 @@ console.log(user); // {"id": 1, "name": "Tim"}
console.log(user.original()); // {"id": 1, "name": "Bob"}
```

## document.toJSON()
## item.toJSON()

This function returns a JSON object representation of the document. This is most commonly used when comparing a document to an object you receive elsewhere without worrying about prototypes.
This function returns a JSON object representation of the item. This is most commonly used when comparing a item to an object you receive elsewhere without worrying about prototypes.

```js
const user = new User({"id": 1, "name": "Tim"});

console.log(user); // Document {"id": 1, "name": "Tim"}
console.log(user); // Item {"id": 1, "name": "Tim"}
console.log(user.toJSON()); // {"id": 1, "name": "Tim"}
```

Due to the fact that a document instance is based on an object it is rare that you will have to use this function since you can access all the properties of the document directly. For example, both of the results will yield the same output.
Due to the fact that a item instance is based on an object it is rare that you will have to use this function since you can access all the properties of the item directly. For example, both of the results will yield the same output.

```js
const user = new User({"id": 1, "name": "Tim"});
Expand Down