-
-
Notifications
You must be signed in to change notification settings - Fork 360
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
17 changed files
with
434 additions
and
23 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,76 @@ | ||
| # Contributor Covenant Code of Conduct | ||
|
|
||
| ## Our Pledge | ||
|
|
||
| In the interest of fostering an open and welcoming environment, we as | ||
| contributors and maintainers pledge to making participation in our project and | ||
| our community a harassment-free experience for everyone, regardless of age, body | ||
| size, disability, ethnicity, sex characteristics, gender identity and expression, | ||
| level of experience, education, socio-economic status, nationality, personal | ||
| appearance, race, religion, or sexual identity and orientation. | ||
|
|
||
| ## Our Standards | ||
|
|
||
| Examples of behavior that contributes to creating a positive environment | ||
| include: | ||
|
|
||
| * Using welcoming and inclusive language | ||
| * Being respectful of differing viewpoints and experiences | ||
| * Gracefully accepting constructive criticism | ||
| * Focusing on what is best for the community | ||
| * Showing empathy towards other community members | ||
|
|
||
| Examples of unacceptable behavior by participants include: | ||
|
|
||
| * The use of sexualized language or imagery and unwelcome sexual attention or | ||
| advances | ||
| * Trolling, insulting/derogatory comments, and personal or political attacks | ||
| * Public or private harassment | ||
| * Publishing others' private information, such as a physical or electronic | ||
| address, without explicit permission | ||
| * Other conduct which could reasonably be considered inappropriate in a | ||
| professional setting | ||
|
|
||
| ## Our Responsibilities | ||
|
|
||
| Project maintainers are responsible for clarifying the standards of acceptable | ||
| behavior and are expected to take appropriate and fair corrective action in | ||
| response to any instances of unacceptable behavior. | ||
|
|
||
| Project maintainers have the right and responsibility to remove, edit, or | ||
| reject comments, commits, code, wiki edits, issues, and other contributions | ||
| that are not aligned to this Code of Conduct, or to ban temporarily or | ||
| permanently any contributor for other behaviors that they deem inappropriate, | ||
| threatening, offensive, or harmful. | ||
|
|
||
| ## Scope | ||
|
|
||
| This Code of Conduct applies both within project spaces and in public spaces | ||
| when an individual is representing the project or its community. Examples of | ||
| representing a project or community include using an official project e-mail | ||
| address, posting via an official social media account, or acting as an appointed | ||
| representative at an online or offline event. Representation of a project may be | ||
| further defined and clarified by project maintainers. | ||
|
|
||
| ## Enforcement | ||
|
|
||
| Instances of abusive, harassing, or otherwise unacceptable behavior may be | ||
| reported by contacting the project team [here](https://charlie.fish/contact). All | ||
| complaints will be reviewed and investigated and will result in a response that | ||
| is deemed necessary and appropriate to the circumstances. The project team is | ||
| obligated to maintain confidentiality with regard to the reporter of an incident. | ||
| Further details of specific enforcement policies may be posted separately. | ||
|
|
||
| Project maintainers who do not follow or enforce the Code of Conduct in good | ||
| faith may face temporary or permanent repercussions as determined by other | ||
| members of the project's leadership. | ||
|
|
||
| ## Attribution | ||
|
|
||
| This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, | ||
| available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html | ||
|
|
||
| [homepage]: https://www.contributor-covenant.org | ||
|
|
||
| For answers to common questions about this code of conduct, see | ||
| https://www.contributor-covenant.org/faq |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,68 @@ | ||
| # Contributing to Dynamoose | ||
|
|
||
| :+1::tada: **THANK YOU** for taking the time to contribute! :tada::+1: | ||
|
|
||
| The following is a set of guidelines for contributing to Dynamoose and all projects in the [dynamoosejs Organization](https://github.com/dynamoosejs) on GitHub. Although these are strongly encouraged guidelines, nothing about this project is set in stone, if you believe something here should be edited, open a PR to start a discussion about it. | ||
|
|
||
| ## Code of Conduct | ||
|
|
||
| This project and everyone participating in it is governed by the [Dynamoose Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the contact method in the [Code of Conduct](CODE_OF_CONDUCT.md). | ||
|
|
||
| ## What should I know before I get started? | ||
|
|
||
| ### Documentation | ||
|
|
||
| All of the documentation for the project is housed within the `docs/docs` folder. The general website is housed within the `docs` folder. It is important while contributing to Dynamoose to ensure that the documentation is complete, up to date, and helpful. | ||
|
|
||
| ### Resources | ||
|
|
||
| It is highly encouraged to read through the following resources before contributing. | ||
|
|
||
| - [README](README.md) | ||
| - [Website](https://dynamoosejs.com) | ||
|
|
||
| ## How Can I Contribute? | ||
|
|
||
| ### Reporting Bugs | ||
|
|
||
| When reporting bugs please fill out the issue template with as much detail as possible. If you do not fill out the issue template with enough detail for us to debug your issue, your issue is at risk for being closed. | ||
|
|
||
| #### Minimal, Complete and Verifiable Example (MCVE) | ||
|
|
||
| One of the most important things when submitting an issue is to provide a *Minimal, Complete and Verifiable Example* (or MCVE for short). If you are reporting a bug it is important for us to be able to test and debug your code as quickly as possible. | ||
|
|
||
| - *Minimal* – Use as little code as possible that still produces the same problem | ||
| - *Complete* – Provide all parts needed to reproduce your problem | ||
| - *Reproducible* – Test the code to make sure it reproduces the problem | ||
|
|
||
| Without following these steps when creating code examples it is nearly impossible for us to debug your issue. Help us help you by putting time and care into code examples. Not following this guideline puts your issue at risk for being closed. | ||
|
|
||
| ### Submitting a PR | ||
|
|
||
| It is highly recommended (although not required) to follow the pattern below before submitting a PR. Not every step below will be relevant to all PRs. | ||
|
|
||
| #### Before | ||
|
|
||
| 1. **Identify a need in the project** - This can be a bug, feature request, or other change. | ||
| 2. **Create a detailed issue to gauge interest** - Although most PRs are merged, we don't want you to waste time creating a PR that doesn't have the support of the community. *Please not this step is highly encouraged for larger contributions, but not required. For smaller contributions (typos, adding tests, updating documentaion, minor code changes, etc.) it is not necessary to create a seperate issue.* | ||
| 3. **Read through the `package.json`** - The `package.json` file in the root of the repository has a **lot** of useful information about the project. Especially read through the scripts section, as a lot of those scripts can help speed up your development process when working in Dynamoose. | ||
|
|
||
| #### During | ||
|
|
||
| 1. **Create a fork & branch** - Before contributing to Dynamoose you must create a fork of the [main repository](https://github.com/dynamoosejs/dynamoose) and create a branch on your fork. It is highly discouraged from using a primary branch (ex. `master` or `alpha`) to make your changes. This is due to the fact that if you enable `Allow edits from maintainers` option, maintainers might commit directly to your primary branch which could cause problems if others are using your fork in their applications. | ||
| 2. **Install dependencies** - Run `npm install` to install all the dependencies of the project. | ||
| 3. **Maintain consistency throughout** - While working in the project, we highly encourage you to maintain the same coding style that the rest of the project uses. This means looking around at similar code and trying to adopt the same style and conventions in your code. | ||
| 4. **Run tests & linter often** - It is highly encouraged to run `npm test` & `npm run lint` often to ensure you are conforming to the project guidelines. In order for a PR to be merged all tests must pass, the linter must throw no errors, and code coverage must not decrease. | ||
| 5. **Write tests** - While (or better yet, before) making changes you should write tests in the test suite to ensure things work as expected. While writing tests try to consider edge cases that might occur and write test for those edge cases (ex. what happens if you a user passes in no arguments, or what happens if the type passed in is not the type you expect). | ||
| 6. **Update documentation** - It is encouraged throughout | ||
| 7. **Commit small & often** - Please commit changes often and keep commit size to a minimum. It is highly discouraged from creating one massive commit with all of your changes in it. Every commit should also aim to pass the linter and tests. Commit messages should also be detailed enough to give a good explaination of the change made. Commit messages such as `changes` or `did stuff` are considered **poor** commit messages. | ||
|
|
||
| #### After | ||
|
|
||
| 1. **Submit the PR** - When submitting the PR it is important to fill out the complete PR template. This ensures reviewers of your PR can easily understand what is going on and make sure all guidelines and requirements have been met. It is also highly recommended to enable the `Allow edits from maintainers` option (be aware that enabling this option means that maintainers have the right to commit to your branch at any time, *we do use this ability*). | ||
| 2. **Be prepared for questions and suggestions** - As others review your PR it is important to be available to answer questions and promptly respond to code suggestions. Stale PRs run the risk of being closed, even if it's a large change or a lot of effort was put into it. | ||
| 3. **Ask others for reviews** - If you know someone who is anticipating your work, ask them to test your branch and leave a detailed review on the PR. | ||
|
|
||
| #### Release | ||
|
|
||
| Dynamoose does not currently have a release schedule that we conform to. We atttempt to batch work into a release every so often. If you have a need that requires us releasing a version sooner, please notify us, and we will attempt to cut a new release earlier (however this is not guaranteed, and you are still welcome to point to a branch in NPM if we are unable to release on your timeline). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,67 @@ | ||
| Dynamoose interacts directly with the [AWS-SDK](https://www.npmjs.com/package/aws-sdk), therefore, it is required that you authenticate and provide valid credentials so Dynamoose can successfully make requests to DynamoDB. | ||
|
|
||
| It is recommended that you do this as early in the application life cycle as possible to prevent issues where Dynamoose will try to make requests to DynamoDB that are unauthenticated. | ||
|
|
||
| There are a few ways to do this. | ||
|
|
||
| ## Environment Variables | ||
|
|
||
| You can use environment variables to setup your configuration. | ||
|
|
||
| ```bash | ||
| export AWS_ACCESS_KEY_ID = "Your AWS Access Key ID" | ||
| export AWS_SECRET_ACCESS_KEY = "Your AWS Secret Access Key" | ||
| export AWS_REGION = "us-east-1" | ||
| ``` | ||
|
|
||
| ## Programatically | ||
|
|
||
| ### Global | ||
|
|
||
| The following code will change the AWS-SDK global settings to use the configuration options. | ||
|
|
||
| ```js | ||
| dynamoose.aws.sdk.config.update({ | ||
| "accessKeyId": "AKID", | ||
| "secretAccessKey": "SECRET", | ||
| "region": "us-east-1" | ||
| }); | ||
| ``` | ||
|
|
||
| ### Dynamoose Specific | ||
|
|
||
| The following code will create a new DynamoDB instance with the specific configuration options and use that in Dynamoose. | ||
|
|
||
| ```js | ||
| // Create new DynamoDB instance | ||
| const ddb = new dynamoose.aws.sdk.DynamoDB({ | ||
| "accessKeyId": "AKID", | ||
| "secretAccessKey": "SECRET", | ||
| "region": "us-east-1" | ||
| }); | ||
|
|
||
| // Set DynamoDB instance to the Dynamoose DDB instance | ||
| dynamoose.aws.ddb.set(ddb); | ||
| ``` | ||
|
|
||
| ## IAM Role | ||
|
|
||
| If you are running Dynamoose in an environment that has an IAM role attached to it (ex. [Lambda](https://aws.amazon.com/lambda/) or [EC2](https://aws.amazon.com/ec2/)), you do not need to do any additional configuration so long as your IAM role has appropriate permissions to access DynamoDB. | ||
|
|
||
| ## Local | ||
|
|
||
| You can also configure Dynamoose to use [DynamoDB Local](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html). | ||
|
|
||
| If your DynamoDB Local server is running on `http://localhost:8000` you can use the following command. | ||
|
|
||
| ```js | ||
| dynamoose.aws.ddb.local(); | ||
| ``` | ||
|
|
||
| Otherwise if your local DynamoDB server is running at a different location you can pass that in as an argument. For example if your server is running at `http://localhost:1234` you can run the following command. | ||
|
|
||
| ```js | ||
| dynamoose.aws.ddb.local("http://localhost:1234"); | ||
| ``` | ||
|
|
||
| Read more about this method [here](/api/Dynamoose#dynamooseawsddblocalendpoint). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| import Tabs from "@theme/Tabs"; | ||
| import TabItem from "@theme/TabItem"; | ||
|
|
||
| In order to use Dynamoose you must import it or require it in your project. This will make the `dynamoose` namespace accessible so you can use things like models, schemas, and more. | ||
|
|
||
| <Tabs | ||
| defaultValue="commonjs" | ||
| values={[ | ||
| {"label": "CommonJS", value: "commonjs"}, | ||
| {"label": "ES Modules", value: "esmodules"}, | ||
| ] | ||
| }> | ||
| <TabItem value="commonjs"> | ||
|
|
||
| ```js | ||
| const dynamoose = require("dynamoose"); | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem value="esmodules"> | ||
|
|
||
| ```js | ||
| import { dynamoose } from "dynamoose"; | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| </Tabs> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| ## Standard | ||
|
|
||
| To install Dynamoose you can run the following command. | ||
|
|
||
| ```bash npm2yarn | ||
| npm install --save dynamoose | ||
| ``` | ||
|
|
||
| ## Prerelease | ||
|
|
||
| At times we will also have prerelease versions of Dynamoose that you can install. An example of this would be the following command. | ||
|
|
||
| ```bash npm2yarn | ||
| npm install --save dynamoose@beta | ||
| ``` | ||
|
|
||
| ## Branch | ||
|
|
||
| You can also install Dynamoose from a specific branch. | ||
|
|
||
| ```bash npm2yarn | ||
| npm install --save dynamoosejs/dynamoose#master | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| ## Description | ||
|
|
||
| Dynamoose is a modeling tool for Amazon's DynamoDB. Dynamoose is heavily inspired by [Mongoose](https://mongoosejs.com/), which means if you are coming from Mongoose the syntax will be very familar. | ||
|
|
||
| ## Key Features | ||
|
|
||
| - Type safety | ||
| - High level API | ||
| - Easy to use syntax | ||
| - Ability to transform data before saving or retrieving documents | ||
| - Strict data modeling (validation, required attributes, and more) | ||
| - Support for DynamoDB Transactions | ||
| - Powerful Conditional/Filtering Support | ||
| - Callback & Promise support | ||
| - And <span style={{ "color": "#1b62d4", "fontSize": "18px" }}>**MANY**</span> more |
Oops, something went wrong.