{"id":25345592,"url":"https://github.com/baseline-js/dynamodb","last_synced_at":"2025-04-08T16:14:50.088Z","repository":{"id":226994914,"uuid":"768063678","full_name":"Baseline-JS/dynamodb","owner":"Baseline-JS","description":"DynamoDB library for simple and optimized way to use AWS DynamoDB","archived":false,"fork":false,"pushed_at":"2024-04-23T02:07:32.000Z","size":334,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-14T12:43:20.561Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Baseline-JS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-06T12:02:12.000Z","updated_at":"2024-07-17T08:34:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"474e5088-349c-42dd-ab30-93e842df4b9f","html_url":"https://github.com/Baseline-JS/dynamodb","commit_stats":null,"previous_names":["baseline-js/baseline-dynamodb","baseline-js/dynamodb"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Baseline-JS%2Fdynamodb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Baseline-JS%2Fdynamodb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Baseline-JS%2Fdynamodb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Baseline-JS%2Fdynamodb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Baseline-JS","download_url":"https://codeload.github.com/Baseline-JS/dynamodb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247878015,"owners_count":21011158,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-14T12:39:08.681Z","updated_at":"2025-04-08T16:14:50.078Z","avatar_url":"https://github.com/Baseline-JS.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Baseline DynamoDB \u003c!-- omit in toc --\u003e\n\nBaseline DynamoDB is an optimized utility library that simplifies standard DynamoDB operations. It's focused towards multi table designed applications, and aims to provide a set of functions that are tailored to the specific use cases of these applications.\n\n## Features \u003c!-- omit in toc --\u003e\n\n- Simplified Item Operations: CRUD with less boilerplate code.\n- Advanced Querying: Easily use sort key conditions, including begins_with and between, to filter queries.\n- Batch Operations: Automatically handles chunking for batch get, batch create, and batch delete operations.\n- Lightweight\n\n## Table of Contents \u003c!-- omit in toc --\u003e\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n  - [Establishing a Connection](#establishing-a-connection)\n  - [Creating an item](#creating-an-item)\n  - [Getting a single item](#getting-a-single-item)\n  - [Updating an item](#updating-an-item)\n  - [Deleting an item](#deleting-an-item)\n  - [Retrieving all items](#retrieving-all-items)\n  - [Querying items](#querying-items)\n- [Extended Usages](#extended-usages)\n  - [Batch Get](#batch-get)\n  - [Batch Create](#batch-create)\n  - [Batch Delete](#batch-delete)\n  - [Query Range](#query-range)\n  - [Query Range Between](#query-range-between)\n  - [Create, Update, Delete Conditions](#create-update-delete-conditions)\n  - [Limit](#limit)\n  - [Projection Expressions](#projection-expressions)\n- [Utility Functions](#utility-functions)\n  - [Unmarshalling](#unmarshalling)\n  - [Marshalling](#marshalling)\n- [Error Handling](#error-handling)\n- [Environment Variables](#environment-variables)\n  - [Serverless Offline](#serverless-offline)\n\n## Installation\n\n```sh\nnpm install @baselinejs/dynamodb\n```\n\n```sh\nyarn add @baselinejs/dynamodb\n```\n\n```sh\npnpm install @baselinejs/dynamodb\n```\n\n## Quick Start\n\n### Establishing a Connection\n\nFirst create a connection to your DynamoDB table.\n\nMust specify a region.\n\nNatively handles both local and deployed environments. See [Environment Variables](#environment-variables) for more information.\n\n```ts\nconst dynamo = getDynamodbConnection({\n  region: 'us-east-1',\n});\n```\n\n### Creating an item\n\nAdd a new item to your table, providing the previously created connection.\n\n```ts\nconst user = await putItem\u003cUser\u003e({\n  dynamoDb: dynamo,\n  table: 'user-table-staging',\n  item: { userId: '123', email: 'example@example.com', name: 'Alice' },\n});\n```\n\n### Getting a single item\n\nGet a single item from your table.\n\n```ts\nconst user = await getItem\u003cUser\u003e({\n  dynamoDb: dynamo,\n  table: 'user-table-staging',\n  key: {\n    userId: '123',\n  },\n});\n```\n\n### Updating an item\n\nUpdate an item in your table.\n\nKey properties will be automatically removed from fields to prevent attribute errors.\n\n```ts\nconst updatedUser = await updateItem\u003cUser\u003e({\n  dynamoDb: dynamo,\n  table: 'user-table-staging',\n  key: {\n    userId: '123',\n  },\n  fields: {\n    name: 'Bob',\n  },\n});\n```\n\n### Deleting an item\n\nDelete an item from your table.\n\n```ts\nconst deletedUser = await deleteItem({\n  dynamoDb: dynamo,\n  table: 'user-table-staging',\n  key: {\n    userId: '123',\n  },\n});\n```\n\n### Retrieving all items\n\nFetch all items from a table.\n\n```ts\nconst allUsers = await getAllItems\u003cUser\u003e({\n  dynamoDb: dynamo,\n  table: 'user-table-staging',\n});\n```\n\n### Querying items\n\nQuery items from an index.\n\n```ts\nconst users = await queryItems\u003cUser\u003e({\n  dynamoDb: dynamo,\n  table: 'user-table-staging',\n  keyName: 'email',\n  keyValue: 'example@example.com',\n  indexName: 'email-index',\n});\n```\n\n## Extended Usages\n\n### Batch Get\n\nBatch get items from a table\nAutomatically handles splitting the keys into chunks of 100.\n\nReturned item order is not necessarily the same as the input order.\n\n```ts\nconst users = await batchGetItems\u003cUser\u003e({\n  dynamoDb: dynamo,\n  table: 'user-table-staging',\n  keys: [{ userId: '123' }, { userId: '456' }],\n});\n```\n\n### Batch Create\n\nBatch create items into a table.\nAutomatically handles splitting the items into chunks of 25.\n\n```ts\nconst users = await batchPutItems\u003cUser\u003e({\n  dynamoDb: dynamo,\n  table: 'user-table-staging',\n  items: [\n    { userId: '123', name: 'Alice' },\n    { userId: '456', name: 'Bob' },\n  ],\n});\n```\n\n### Batch Delete\n\nBatch delete items from a table.\nAutomatically handles splitting the keys into chunks of 25.\n\n```ts\nconst isDeleted = await batchDeleteItems({\n  dynamoDb: dynamo,\n  table: 'user-table-staging',\n  keys: [{ userId: '123' }, { userId: '456' }],\n});\n```\n\n### Query Range\n\nQuery items from a table with a range key.\n\n```ts\nconst userPurchases = await queryItemsRange\u003cPurchase\u003e({\n  dynamoDb: dynamo,\n  table: 'purchase-table-staging',\n  keyName: 'userId',\n  keyValue: '123',\n  rangeKeyName: 'createdAt',\n  rangeKeyValue: '2022',\n  // Fuzzy search will use a begins_with condition\n  fuzzy: true,\n  indexName: 'userId-createdAt-index',\n});\n```\n\nEquivalent query using `queryItems`\n\n```ts\nconst userPurchases = await queryItems\u003cPurchase\u003e({\n  dynamoDb: dynamo,\n  table: 'purchase-table-staging',\n  keyName: 'userId',\n  keyValue: '123',\n  indexName: 'userId-createdAt-index',\n  rangeCondition: {\n    operator: 'BeginsWith',\n    field: 'createdAt',\n    value: '2022',\n  },\n});\n```\n\n### Query Range Between\n\nQuery items from a table with a range key between two values.\n\n```ts\nconst userPurchases = await queryItemsRangeBetween\u003cPurchase\u003e({\n  dynamoDb: dynamo,\n  table: 'purchase-table-staging',\n  keyName: 'userId',\n  keyValue: '123',\n  rangeKeyName: 'createdAt',\n  rangeKeyValueMin: '2022-01-01T00:00:00.000Z',\n  rangeKeyValueMax: '2023-01-01T00:00:00.000Z',\n  indexName: 'userId-createdAt-index',\n});\n```\n\nEquivalent query using `queryItems`\n\n```ts\nconst userPurchases = await queryItems\u003cPurchase\u003e({\n  dynamoDb: dynamo,\n  table: 'purchase-table-staging',\n  keyName: 'userId',\n  keyValue: '123',\n  indexName: 'userId-createdAt-index',\n  rangeCondition: {\n    operator: 'Between',\n    field: 'createdAt',\n    value: '2022-01-01T00:00:00.000Z',\n    betweenSecondValue: '2023-01-01T00:00:00.000Z',\n  },\n});\n```\n\n### Create, Update, Delete Conditions\n\nA `conditions` array can be provided to the `putItem`, `updateItem`, and `deleteItem` functions to specify conditions that must be met for the operation to succeed.\n\nConditions are combined with AND.\n\n```ts\ntry {\n  const user = await putItem\u003cUser\u003e({\n    dynamoDb: dynamo,\n    table: 'user-table-staging',\n    item: { userId: '123', email: 'example2@example.com', name: 'Alice' },\n    conditions: [\n      {\n        // Only create if this userId does not already exist\n        operator: 'AttributeNotExists',\n        field: 'userId',\n      },\n    ],\n  });\n} catch (error) {\n  if (error.name === 'ConditionalCheckFailedException') {\n    // error.Item contains the item that already exists with the specified userId\n  }\n}\n```\n\n### Limit\n\nYou can limit the number of items returned by specifying the `limit` parameter.\nThis applies to the `query` functions as well as the `getAllItems` function.\n\nThe function will handle pagination internally up until the limit is reached.\n\n```ts\nconst userPurchases = await queryItems\u003cPurchase\u003e({\n  dynamoDb: dynamo,\n  table: 'purchase-table-staging',\n  keyName: 'userId',\n  keyValue: '123',\n  limit: 10,\n});\n```\n\n### Projection Expressions\n\nProjection expressions are used to limit the attributes returned from a query to only the specified fields.\n\nTo maintain type safety, you can specify the fields you want to return using the second generic type parameter.\n\n```ts\nconst userPurchases = await queryItems\u003cPurchase, 'userId' | 'createdAt'\u003e({\n  dynamoDb: dynamo,\n  table: 'purchase-table-staging',\n  keyName: 'userId',\n  keyValue: '123',\n  projectionExpression: ['userId', 'createdAt'],\n});\n```\n\n## Utility Functions\n\n### Unmarshalling\n\nUnmarshalling is used to convert a DynamoDB record into a JavaScript object.\n\nThis is useful when using dynamodb streams, as the new and old images are returned as DynamoDB records that need to be unmarshalled.\n\n```ts\nconst user = unmarshallItem\u003cUser\u003e(record.dynamodb?.NewImage);\n```\n\n### Marshalling\n\nMarshalling is used to convert a JavaScript object into a DynamoDB record.\n\n```ts\nconst user = {\n  userId: '123',\n  email: 'example@example.com',\n  name: 'Alice',\n};\nconst marshalledUser = marshallItem(user);\n```\n\n## Error Handling\n\nErrors are not caught internally but are instead propagated up to the calling code.\n\nTo handle these errors effectively, wrap function calls in try-catch blocks in your application. This allows for custom error handling strategies, such as logging errors or retrying failed operations.\n\n## Environment Variables\n\n### Serverless Offline\n\n`IS_OFFLINE`\n\nWill be `\"true\"` in your handlers when using serverless-offline.\nWhen `\"true\"` will use values appropriate to work with DynamoDB Local.\n\n```\nregion: \"localhost\",\nendpoint: \"http://localhost:8000\",\n```\n\n`FORCE_ONLINE`\n\nSet to `\"true\"` to override the `IS_OFFLINE` environment variable and use a deployed DynamoDB instance.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbaseline-js%2Fdynamodb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbaseline-js%2Fdynamodb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbaseline-js%2Fdynamodb/lists"}