{"_id":"@denis_bruns/nosql-dynamodb","_rev":"1-dcce2573095d4df4e030d3785cc4e9c7","name":"@denis_bruns/nosql-dynamodb","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@denis_bruns/nosql-dynamodb","version":"0.1.0","keywords":["clean-architecture","typescript","gateway"],"author":{"name":"denis_bruns@protonmail.com"},"license":"MIT","_id":"@denis_bruns/nosql-dynamodb@0.1.0","maintainers":[{"name":"denis_bruns","email":"denis_bruns@protonmail.com"}],"dist":{"shasum":"0a012bab69f25ff9d8f9700b505873411153b61a","tarball":"https://registry.npmjs.org/@denis_bruns/nosql-dynamodb/-/nosql-dynamodb-0.1.0.tgz","fileCount":25,"integrity":"sha512-71dNY+1lyorelSmGysSsxfKAieQFWtBq392bmANUxHoF74deNvkhv1Z/tnBD/5wDSof4XixkRjO4uelArkUM2A==","signatures":[{"sig":"MEUCIFU2gv8GezdojzWzqu+U7CSllney9UZ8uPawYaMCKFY3AiEAoOC3/AAcLTNJpLIkNgYwHSMEd9JlGhTDn1ezRLvOTQQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":51752},"main":"./dist/index.js","types":"./dist/types/index.d.ts","exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"}},"gitHead":"7cdbb603159eca9e99d27e4a4580df22a0cb3f9f","scripts":{"jest":"jest","lint":"eslint src/lib --ext .ts","test":"jest src/tests --detectOpenHandles --forceExit","build":"tsc && npm run postbuild","clean":"rimraf dist","release":"bash release.sh patch","postbuild":"cp package.json README.md dist/","release:major":"bash release.sh major","release:minor":"bash release.sh minor","release:patch":"bash release.sh patch","prepublishOnly":"npm cache clean && npm run build","release:premajor":"bash release.sh premajor","release:prepatch":"bash release.sh prepatch","release:premminor":"bash release.sh preminor","release:prerelease":"bash release.sh prerelease"},"_npmUser":{"name":"denis_bruns","email":"denis_bruns@protonmail.com"},"_npmVersion":"10.8.2","description":"> **A robust DynamoDB service for clean architecture projects, featuring filter expressions, pagination, and injection-safe validations.**","directories":{},"_nodeVersion":"18.20.5","dependencies":{"@denis_bruns/core":"^0.1.0","@aws-sdk/client-dynamodb":"^3.726.1","@denis_bruns/database-core":"^0.1.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","ts-jest":"^29.2.5","ts-node":"^10.9.2","typescript":"^5.7.2","@types/jest":"^29.5.14","axios-mock-adapter":"^2.1.0"},"_npmOperationalInternal":{"tmp":"tmp/nosql-dynamodb_0.1.0_1737667025827_0.15846368053769844","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@denis_bruns/nosql-dynamodb","version":"0.1.1","main":"./dist/index.js","types":"./dist/types/index.d.ts","exports":{".":{"require":"./dist/index.js","import":"./dist/index.js","types":"./dist/types/index.d.ts"}},"scripts":{"build":"tsc && npm run postbuild","postbuild":"cp package.json README.md dist/","lint":"eslint src/lib --ext .ts","clean":"rimraf dist","prepublishOnly":"npm cache clean && npm run build","release":"bash release.sh patch","release:prerelease":"bash release.sh prerelease","release:minor":"bash release.sh minor","release:major":"bash release.sh major","release:patch":"bash release.sh patch","release:prepatch":"bash release.sh prepatch","release:premminor":"bash release.sh preminor","release:premajor":"bash release.sh premajor","jest":"jest","test":"jest src/tests --detectOpenHandles --forceExit"},"keywords":["clean-architecture","typescript","gateway"],"author":{"name":"denis_bruns@protonmail.com"},"license":"MIT","dependencies":{"@aws-sdk/client-dynamodb":"^3.726.1","@denis_bruns/database-core":"^0.1.0","@denis_bruns/core":"^0.1.0"},"devDependencies":{"@types/jest":"^29.5.14","axios-mock-adapter":"^2.1.0","jest":"^29.7.0","ts-jest":"^29.2.5","ts-node":"^10.9.2","typescript":"^5.7.2"},"_id":"@denis_bruns/nosql-dynamodb@0.1.1","gitHead":"1575968a8ada11934640f2dd41fc8e23ac0757e8","description":"> **A robust DynamoDB service for clean architecture projects, featuring filter expressions, pagination, and injection-safe validations.**","_nodeVersion":"18.20.5","_npmVersion":"10.8.2","dist":{"integrity":"sha512-1Ym6PonGWkU9ZJaxX0E9dZxyWxV5AkmetcSlmFqnbl4G4lULDxmC37MfVRn6OWAWDIvqAzyGN74X95mcHgMsFw==","shasum":"0f219a4a0fc1062d25bc0deda30ea3def172b07b","tarball":"https://registry.npmjs.org/@denis_bruns/nosql-dynamodb/-/nosql-dynamodb-0.1.1.tgz","fileCount":25,"unpackedSize":51608,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDVLu2nUGc1HEkN+i9mKsdyiAOsBYi3F5NC8a7PSmPP6AIhAK9QG6fs83ywtIfwU2TpW/M9oKbgsmRqKo/shWFKHim9"}]},"_npmUser":{"name":"denis_bruns","email":"denis_bruns@protonmail.com"},"directories":{},"maintainers":[{"name":"denis_bruns","email":"denis_bruns@protonmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/nosql-dynamodb_0.1.1_1737668742213_0.408908668598303"},"_hasShrinkwrap":false}},"time":{"created":"2025-01-23T21:17:05.706Z","modified":"2025-01-23T21:45:42.621Z","0.1.0":"2025-01-23T21:17:06.878Z","0.1.1":"2025-01-23T21:45:42.429Z"},"author":{"name":"denis_bruns@protonmail.com"},"license":"MIT","keywords":["clean-architecture","typescript","gateway"],"description":"> **A robust DynamoDB service for clean architecture projects, featuring filter expressions, pagination, and injection-safe validations.**","maintainers":[{"name":"denis_bruns","email":"denis_bruns@protonmail.com"}],"readme":"# @denis_bruns/nosql-dynamodb\n\n> **A robust DynamoDB service for clean architecture projects, featuring filter expressions, pagination, and injection-safe validations.**\n\n[![NPM Version](https://img.shields.io/npm/v/@denis_bruns/nosql-dynamodb?style=flat-square&logo=npm)](https://www.npmjs.com/package/@denis_bruns/nosql-dynamodb)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)\n[![GitHub](https://img.shields.io/badge/GitHub--181717.svg?style=flat-square&logo=github)](https://github.com/h3llf1r33/nosql-dynamodb)\n\n---\n\n## Overview\n\n`@denis_bruns/nosql-dynamodb` provides a **DynamoDB-specific** data service built around clean architecture principles. It extends the functionality of [`@denis_bruns/database-core`](https://www.npmjs.com/package/@denis_bruns/database-core) to offer:\n\n- **Type-safe** query building via `DynamoDBExpressionBuilder`\n- **Partition key** and **filter** expression support\n- **Pagination** handling, including **sorting** and offset-based slicing\n- **Validation** utilities to guard against potential NoSQL injection\n- Seamless integration with the **AWS SDK** for DynamoDB\n\nIf you’re looking to unify your **business logic** and **data access** in a clean, testable manner, this package is an excellent place to start.\n\n---\n\n## Key Features\n\n1. **DynamoDB-Specific Expression Builder**\n- Converts filter queries into `KeyConditionExpression`, `FilterExpression`, and attribute maps.\n- Supports operators like `=`, `<`, `<=`, `>`, `>=`, `!=`, `in`, `not in`, `like`, and `not like`.\n\n2. **Automatic Query vs. Scan Selection**\n- If your query includes a partition key (`pkName`), it uses a `QueryCommand`.\n- Otherwise, it defaults to a `ScanCommand`.\n\n3. **Pagination & Sorting**\n- Built-in pagination checks (`limit`, `offset`, `page`).\n- Sorting is handled by setting `ScanIndexForward` for queries or by sorting scanned results in memory (for non-key fields).\n\n4. **Type-Safe Results**\n- The service converts raw DynamoDB `AttributeValue` objects into typed entities.\n- JSON properties, nested maps, arrays, and booleans are all mapped back to JavaScript types.\n\n5. **Injection-Safe Validations**\n- Guards against malicious operators like `$where`, `$regex`, and others.\n- Ensures field names are valid and do not exceed depth or length limits.\n\n---\n\n## Installation\n\nWith **npm**:\n\n```bash\nnpm install @denis_bruns/nosql-dynamodb\n```\n\nOr with **yarn**:\n\n```bash\nyarn add @denis_bruns/nosql-dynamodb\n```\n\nYou’ll also need the AWS DynamoDB client:\n\n```bash\nnpm install @aws-sdk/client-dynamodb\n```\n\n---\n\n## Usage Example\n\nBelow is a **basic** usage demonstration. In practice, you’d integrate this into your domain logic or repository layer.\n\n```ts\nimport { DynamoDBClient } from \"@aws-sdk/client-dynamodb\";\nimport {\nfetchWithFiltersAndPaginationDynamoDb,\nDynamoDBService,\n} from \"@denis_bruns/nosql-dynamodb\";\nimport { IGenericFilterQuery } from \"@denis_bruns/core\";\n\nasync function demo() {\nconst client = new DynamoDBClient({ region: \"us-east-1\" });\n\n// Example filter query: fetch items by a \"status\" field, limited to 5 results\nconst query: IGenericFilterQuery = {\nfilters: [\n{ field: \"status\", operator: \"=\", value: \"active\" }\n],\npagination: { page: 1, limit: 5 }\n};\n\n// Option A: Direct helper function\nconst directResult = await fetchWithFiltersAndPaginationDynamoDb<MyItem>(\n\"my-table\",\nquery,\nclient\n);\nconsole.log(\"Direct Helper Results:\", directResult.data);\n\n// Option B: Using the DynamoDBService instance directly\nconst service = new DynamoDBService(\"my-table\", \"id\"); // \"id\" is the partition key\nconst serviceResult = await service.fetchWithFiltersAndPagination<MyItem>(query, client);\nconsole.log(\"Service Class Results:\", serviceResult.data);\n}\n\ninterface MyItem {\nid: string;\nstatus: string;\ncreatedAt: string;\n// ... other fields\n}\n```\n\nIn this snippet:\n- **`fetchWithFiltersAndPaginationDynamoDb`** quickly fetches data from DynamoDB, applying filters and pagination.\n- **`DynamoDBService`** is more extensible if you need to override methods or customize expression handling.\n\n---\n\n## Core Concepts\n\n### 1. Filter Expressions\n\nThe library uses a `filters` array where each filter has `field`, `operator`, and `value`. Example:\n\n```ts\nfilters: [\n{ field: \"category\", operator: \"=\", value: \"books\" },\n{ field: \"price\", operator: \">\", value: 20 }\n]\n```\n\n**Supported Operators**: `<`, `<=`, `>`, `>=`, `=`, `!=`, `in`, `not in`, `like`, `not like`.\n\n### 2. Pagination & Sorting\n\n- **Pagination** properties: `page`, `limit`, `offset`.\n- **Sorting**: if `pagination.sortBy` is set to the partition key or sort key, DynamoDB’s native sort can be used. Otherwise, items are sorted in memory.\n\n### 3. Validation\n\n- **`validateFieldName`** ensures fields are free of unsafe patterns and exceed neither max depth nor length.\n- **`validateValue`** checks for NoSQL injection attempts and invalid input types.\n- **`validatePagination`** ensures `page`, `limit`, `offset` are integers.\n\n---\n\n## Related Packages\n\n- **@denis_bruns/core**\n  [![NPM](https://img.shields.io/npm/v/@denis_bruns/core?style=flat-square&logo=npm)](https://www.npmjs.com/package/@denis_bruns/core)  \n  [![GitHub](https://img.shields.io/badge/GitHub--181717.svg?style=flat-square&logo=github)](https://github.com/h3llf1r33/core)  \n  *Provides the fundamental interfaces and types used by this library.*\n\n- **@denis_bruns/database-core**\n  [![NPM](https://img.shields.io/npm/v/@denis_bruns/database-core?style=flat-square&logo=npm)](https://www.npmjs.com/package/@denis_bruns/database-core)  \n  [![GitHub](https://img.shields.io/badge/GitHub--181717.svg?style=flat-square&logo=github)](https://github.com/h3llf1r33/database-core)  \n  *A foundational database service layer that this package extends for DynamoDB usage.*\n\n---\n\n## Contributing\n\nContributions are welcome! If you find a bug or have a feature request, feel free to open an issue or submit a pull request on [GitHub](https://github.com/h3llf1r33/nosql-dynamodb).\n\n---\n\n## License\n\nThis project is [MIT licensed](LICENSE).\n\n---\n\n<p align=\"center\">\nBuilt with ❤️ by <a href=\"https://github.com/h3llf1r33\">h3llf1r33</a>\n</p>","readmeFilename":"README.md"}