A progressive Node.js framework for building efficient and scalable server-side applications.
\n
\n\n\n\n\n\n\n\n\n\n \n \n
\n \n\n## Description\n\nAzure Database ([Table Storage](http://bit.ly/nest_azure-storage-table), [Cosmos DB](https://azure.microsoft.com/en-us/services/cosmos-db/) and more) module for [Nest](https://github.com/nestjs/nest) framework (node.js)\n\n## Tutorial\n\nLearn how to get started with [Azure table storage for NestJS](https://trilon.io/blog/nestjs-nosql-azure-table-storage)\n\n## Before Installation\n\nFor Table Storage\n\n1. Create a Storage account and resource ([read more](http://bit.ly/nest_new-azure-storage-account))\n1. For [Table Storage](http://bit.ly/nest_azure-storage-table), In the [Azure Portal](https://portal.azure.com), go to **Dashboard > Storage > _your-storage-account_**.\n1. Note down the \"Storage account name\" and \"Connection string\" obtained at **Access keys** under **Settings** tab.\n\nFor Cosmos DB\n\n1. Create a Cosmos DB account and resource ([read more](https://azure.microsoft.com/en-us/services/cosmos-db/))\n1. For [Cosmos DB](http://bit.ly/nest_azure-storage-table), In the [Azure Portal](https://portal.azure.com), go to **Dashboard > Azure Cosmos DB > _your-cosmos-db-account_**.\n1. Note down the \"URI\" and \"Primary Key\" obtained at **Keys** under **Settings** tab.\n\n## Installation\n\n```bash\n$ npm i --save @nestjs/azure-database\n```\n\n## Usage\n\n### For Azure Table Storage support\n\n1. Create or update your existing `.env` file with the following content:\n\n```\nAZURE_STORAGE_CONNECTION_STRING=\n```\n\n2. **IMPORTANT: Make sure to add your `.env` file to your .gitignore! The `.env` file MUST NOT be versioned on Git.**\n\n3. Make sure to include the following call to your main file:\n\n```typescript\nif (process.env.NODE_ENV !== 'production') require('dotenv').config();\n```\n\n> This line must be added before any other imports!\n\n### Example\n\n#### Prepare your entity\n\n0. Create a new feature module, eg. with the nest CLI:\n\n```shell\n$ nest generate module contact\n```\n\n1. Create a Data Transfer Object (DTO) inside a file named `contact.dto.ts`:\n\n```typescript\nexport class ContactDTO {\n name: string;\n message: string;\n}\n```\n\n2. Create a file called `contact.entity.ts` and describe the entity model using the provided decorators:\n\n- `@EntityPartitionKey(value: string)`: Represents the `PartitionKey` of the entity (**required**).\n\n- `@EntityRowKey(value: string)`: Represents the `RowKey` of the entity (**required**).\n\n- `@EntityInt32(value?: string)`: For signed 32-bit integer values.\n\n- `@EntityInt64(value?: string)`: For signed 64-bit integer values.\n\n- `@EntityBinary(value?: string)`: For binary (blob) data.\n\n- `@EntityBoolean(value?: string)`: For `true` or `false` values.\n\n- `@EntityString(value?: string)`: For character data.\n\n- `@EntityDouble(value?: string)`: For floating point numbers with 15 digit precision.\n\n- `@EntityDateTime(value?: string)`: For time of day.\n\nFor instance, the shape of the following entity:\n\n```typescript\nimport { EntityPartitionKey, EntityRowKey, EntityString } from '@nestjs/azure-database';\n\n@EntityPartitionKey('ContactID')\n@EntityRowKey('ContactName')\nexport class Contact {\n @EntityString() name: string;\n @EntityString() message: string;\n}\n```\n\nWill be automatically converted to:\n\n```json\n{\n \"PartitionKey\": { \"_\": \"ContactID\", \"$\": \"Edm.String\" },\n \"RowKey\": { \"_\": \"ContactName\", \"$\": \"Edm.String\" },\n \"name\": { \"_\": undefined, \"$\": \"Edm.String\" },\n \"message\": { \"_\": undefined, \"$\": \"Edm.String\" }\n}\n```\n\n> Note: The provided entity type annotations represent the [Entity Data Model][edm-types] types.\n\n3. Import the `AzureTableStorageModule` inside your Nest feature module `contact.module.ts`:\n\n```typescript\nimport { Module } from '@nestjs/common';\nimport { AzureTableStorageModule } from '@nestjs/azure-database';\nimport { ContactController } from './contact.controller';\nimport { ContactService } from './contact.service';\nimport { Contact } from './contact.entity';\n\n@Module({\n imports: [AzureTableStorageModule.forFeature(Contact)],\n providers: [ContactService],\n controllers: [ContactController],\n})\nexport class ContactModule {}\n```\n\nYou can optionally pass in the following arguments:\n\n```typescript\nAzureTableStorageModule.forFeature(Contact, {\n table: 'AnotherTableName',\n createTableIfNotExists: true,\n});\n```\n\n- `table: string`: The name of the table. If not provided, the name of the `Contact` entity will be used as a table name\n- `createTableIfNotExists: boolean`: Whether to automatically create the table if it doesn't exists or not:\n - If `true` the table will be created during the startup of the app.\n - If `false` the table will not be created. **You will have to create the table by yourself before querying it!**\n\n#### CRUD operations\n\n0. Create a service that will abstract the CRUD operations:\n\n```shell\n$ nest generate service contact\n```\n\n1. Use the `@InjectRepository(Contact)` to get an instance of the Azure `Repository` for the entity definition created earlier:\n\n```typescript\nimport { Injectable } from '@nestjs/common';\nimport { Repository, InjectRepository } from '@nestjs/azure-database';\nimport { Contact } from './contact.entity';\n\n@Injectable()\nexport class ContactService {\n constructor(\n @InjectRepository(Contact)\n private readonly contactRepository: Repository,\n ) {}\n}\n```\n\nThe `AzureTableStorageRepository` provides a couple of public APIs and Interfaces for managing various CRUD operations:\n\n##### CREATE\n\n`create(entity: T, rowKeyValue?: string): Promise`: creates a new entity.\n\n```typescript\n\n @Post()\n async create(contact: Contact, rowKeyValue: string): Promise {\n //if rowKeyValue is null, rowKeyValue will generate a UUID\n return this.contactRepository.create(contact, rowKeyValue)\n }\n```\n\n##### READ\n\n`find(rowKey: string, entity: Partial): Promise`: finds one entity using its `RowKey`.\n\n```typescript\n @Get(':rowKey')\n async getContact(@Param('rowKey') rowKey) {\n try {\n return await this.contactRepository.find(rowKey, new Contact());\n } catch (error) {\n // Entity not found\n throw new UnprocessableEntityException(error);\n }\n }\n```\n\n`findAll(tableQuery?: azure.TableQuery, currentToken?: azure.TableService.TableContinuationToken): Promise>`: finds all entities that match the given query (return all entities if no query provided).\n\n```typescript\n @Get()\n async getAllContacts() {\n return await this.contactRepository.findAll();\n }\n```\n\n##### UPDATE\n\n`update(rowKey: string, entity: Partial): Promise`: Updates an entity. It does a partial update.\n\n```typescript\n @Put(':rowKey')\n async saveContact(@Param('rowKey') rowKey, @Body() contactData: ContactDTO) {\n try {\n const contactEntity = new Contact();\n // Disclaimer: Assign only the properties you are expecting!\n Object.assign(contactEntity, contactData);\n\n return await this.contactRepository.update(rowKey, contactEntity);\n } catch (error) {\n throw new UnprocessableEntityException(error);\n }\n }\n @Patch(':rowKey')\n async updateContactDetails(@Param('rowKey') rowKey, @Body() contactData: Partial) {\n try {\n const contactEntity = new Contact();\n // Disclaimer: Assign only the properties you are expecting!\n Object.assign(contactEntity, contactData);\n\n return await this.contactRepository.update(rowKey, contactEntity);\n } catch (error) {\n throw new UnprocessableEntityException(error);\n }\n }\n```\n\n##### DELETE\n\n`delete(rowKey: string, entity: T): Promise`: Removes an entity from the database.\n\n```typescript\n\n @Delete(':rowKey')\n async deleteDelete(@Param('rowKey') rowKey) {\n try {\n const response = await this.contactRepository.delete(rowKey, new Contact());\n\n if (response.statusCode === 204) {\n return null;\n } else {\n throw new UnprocessableEntityException(response);\n }\n } catch (error) {\n throw new UnprocessableEntityException(error);\n }\n }\n```\n\n### For Azure Cosmos DB support\n\n1. Create or update your existing `.env` file with the following content:\n\n```\nAZURE_COSMOS_DB_NAME=\nAZURE_COSMOS_DB_ENDPOINT=\nAZURE_COSMOS_DB_KEY=\n```\n\n2. **IMPORTANT: Make sure to add your `.env` file to your .gitignore! The `.env` file MUST NOT be versioned on Git.**\n\n3. Make sure to include the following call to your main file:\n\n```typescript\nif (process.env.NODE_ENV !== 'production') require('dotenv').config();\n```\n\n> This line must be added before any other imports!\n\n### Example\n\n> Note: Check out the CosmosDB example project included in the [sample folder](https://github.com/nestjs/azure-database/tree/master/sample/cosmos-db)\n\n#### Prepare your entity\n\n0. Create a new feature module, eg. with the nest CLI:\n\n```shell\n$ nest generate module event\n```\n\n1. Create a Data Transfer Object (DTO) inside a file named `event.dto.ts`:\n\n```typescript\nexport class EventDTO {\n name: string;\n type: string;\n date: Date;\n location: Point;\n}\n```\n\n2. Create a file called `event.entity.ts` and describe the entity model using the provided decorators:\n\n- `@CosmosPartitionKey(value: string)`: Represents the `PartitionKey` of the entity (**required**).\n\n- `@CosmosDateTime(value?: string)`: For DateTime values.\n\nFor instance, the shape of the following entity:\n\n```typescript\nimport { CosmosPartitionKey, CosmosDateTime, Point } from '@nestjs/azure-database';\n\n@CosmosPartitionKey('type')\nexport class Event {\n id?: string;\n type: string;\n @CosmosDateTime() createdAt: Date;\n location: Point;\n}\n```\n\nWill be automatically converted to:\n\n```json\n{\n \"type\": \"Meetup\",\n \"createdAt\": \"2019-11-15T17:05:25.427Z\",\n \"position\": {\n \"type\": \"Point\",\n \"coordinates\": [2.3522, 48.8566]\n }\n}\n```\n\n3. Import the `AzureCosmosDbModule` inside your Nest feature module `event.module.ts`:\n\n```typescript\nimport { Module } from '@nestjs/common';\nimport { AzureCosmosDbModule } from '@nestjs/azure-database';\nimport { EventController } from './event.controller';\nimport { EventService } from './event.service';\nimport { Event } from './event.entity';\n\n@Module({\n imports: [\n AzureCosmosDbModule.forRoot({\n dbName: process.env.AZURE_COSMOS_DB_NAME,\n endpoint: process.env.AZURE_COSMOS_DB_ENDPOINT,\n key: process.env.AZURE_COSMOS_DB_KEY,\n }),\n AzureCosmosDbModule.forFeature([{ dto: Event }]),\n ],\n providers: [EventService],\n controllers: [EventController],\n})\nexport class EventModule {}\n```\n\n#### CRUD operations\n\n0. Create a service that will abstract the CRUD operations:\n\n```shell\n$ nest generate service event\n```\n\n1. Use the `@InjectModel(Event)` to get an instance of the Azure Cosmos DB [Container](https://docs.microsoft.com/en-us/javascript/api/@azure/cosmos/container) for the entity definition created earlier:\n\n```typescript\nimport { Injectable } from '@nestjs/common';\nimport { InjectModel } from '@nestjs/azure-database';\nimport { Event } from './event.entity';\n\n@Injectable()\nexport class EventService {\n constructor(\n @InjectModel(Event)\n private readonly eventContainer,\n ) {}\n}\n```\n\nThe Azure Cosmos DB `Container` provides a couple of public APIs and Interfaces for managing various CRUD operations:\n\n##### CREATE\n\n`create(entity: T): Promise`: creates a new entity.\n\n```typescript\n\n @Post()\n async create(event: Event): Promise {\n return this.eventContainer.items.create(event)\n }\n\n```\n\n##### READ\n\n`query(query: string | SqlQuerySpec, options?: FeedOptions): QueryIterator`: run a SQL Query to find a document.\n\n```typescript\n @Get(':id')\n async getContact(@Param('id') id) {\n try {\n const querySpec = {\n query: \"SELECT * FROM root r WHERE r.id=@id\",\n parameters: [\n {\n name: \"@id\",\n value: id\n }\n ]\n };\n const { resources } = await this.eventContainer.items.query(querySpec).fetchAll()\n return resources\n } catch (error) {\n // Entity not found\n throw new UnprocessableEntityException(error);\n }\n }\n```\n\n##### UPDATE\n\n`read(options?: RequestOptions): Promise>`: Get a document.\n`replace(body: T, options?: RequestOptions): Promise>`: Updates a document.\n\n```typescript\n @Put(':id')\n async saveEvent(@Param('id') id, @Body() eventData: EventDTO) {\n try {\n const { resource: item } = await this.eventContainer.item(id, 'type').read()\n\n // Disclaimer: Assign only the properties you are expecting!\n Object.assign(item, eventData);\n\n const { resource: replaced } = await this.eventContainer\n .item(id, 'type')\n .replace(item)\n return replaced\n } catch (error) {\n throw new UnprocessableEntityException(error);\n }\n }\n```\n\n##### DELETE\n\n`delete(options?: RequestOptions): Promise>`: Removes an entity from the database.\n\n```typescript\n\n @Delete(':id')\n async deleteEvent(@Param('id') id) {\n try {\n const { resource: deleted } = await this.eventContainer\n .item(id, 'type')\n .delete()\n\n return deleted;\n } catch (error) {\n throw new UnprocessableEntityException(error);\n }\n }\n```\n\n## Support\n\nNest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support).\n\n## Stay in touch\n\n- Author - [Wassim Chegham](https://wassim.dev)\n- Website - [https://wassim.dev](https://wassim.dev/)\n- Twitter - [@manekinekko](https://twitter.com/manekinekko)\n\n## License\n\nNest is [MIT licensed](LICENSE).\n\n[edm-types]: http://bit.ly/nest-edm\n","readmeFilename":"README.md"}
![\"Nest](\"https://nestjs.com/img/logo_text.svg\"){kind=logo}
\n![\"NPM](\"https://img.shields.io/npm/v/@nestjs/core.svg\")
\n![\"Package](\"https://img.shields.io/npm/l/@nestjs/core.svg\")
\n![\"NPM](\"https://img.shields.io/npm/dm/@nestjs/core.svg\")
\n![\"Travis\"](\"https://api.travis-ci.org/nestjs/nest.svg?branch=master\")
\n![\"Linux\"](\"https://img.shields.io/travis/nestjs/nest/master.svg?label=linux\")
\n![\"Coverage\"](\"https://coveralls.io/repos/github/nestjs/nest/badge.svg?branch=master#5\"){kind=icon}
\n![\"Discord\"/](\"https://img.shields.io/badge/discord-online-brightgreen.svg\"){kind=icon}
\n![\"Backers](\"https://opencollective.com/nest/backers/badge.svg\"){kind=icon}
\n![\"Sponsors](\"https://opencollective.com/nest/sponsors/badge.svg\"){kind=icon}
\n ![](\"https://img.shields.io/badge/Donate-PayPal-dc3d53.svg\"/){kind=icon}
\n ![](\"https://img.shields.io/twitter/follow/nestframework.svg?style=social&label=Follow\")
\n