# nestjs-azure-cosmos
> The Azure cosmos db for Nest framework (node.js)
Latest version **2.4.0** (published 2023-10-06) · MIT license · 0 weekly downloads
## Install
```sh
npm install nestjs-azure-cosmos
pnpm add nestjs-azure-cosmos
yarn add nestjs-azure-cosmos
bun add nestjs-azure-cosmos
```
## Health
**Score 25/100 (F)** — status: abandoned.
Positive: has types; no vulnerabilities; high quality score.
Warnings: low downloads; no esm support.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 2.4.0 |
| Published | 2023-10-06 |
| First published | 2023-05-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 77.1 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 0 |
| Maintainers | swapnil16 |
## Links
- npm: https://www.npmjs.com/package/nestjs-azure-cosmos
- Repository: https://github.com/swapnilgawade16/nestjs-azure-cosmos
- Homepage: https://github.com/swapnilgawade16/nestjs-azure-cosmos#readme
- Issues: https://github.com/swapnilgawade16/nestjs-azure-cosmos/issues
- npm.io page: https://npm.io/package/nestjs-azure-cosmos
## Dependencies (4)
- [@nestjs/core](https://npm.io/package/@nestjs/core.md) ^10.2.7
- [@azure/cosmos](https://npm.io/package/@azure/cosmos.md) ^3.16.2
- [@nestjs/common](https://npm.io/package/@nestjs/common.md) ^10.2.7
- [@azure/ms-rest-js](https://npm.io/package/@azure/ms-rest-js.md) ^2.6.1
## Recent versions
- 2.4.0 (latest) — 2023-10-06
- 2.3.2 — 2023-10-06
- 2.3.1 — 2023-05-05
- 2.3.0 — 2023-05-05
## README
[travis-image]: https://api.travis-ci.org/nestjs/nest.svg?branch=master
[travis-url]: https://travis-ci.org/nestjs/nest
[linux-image]: https://img.shields.io/travis/nestjs/nest/master.svg?label=linux
[linux-url]: https://travis-ci.org/nestjs/nest
A progressive Node.js framework for building efficient and scalable server-side applications.
## Description
---
This is forked from https://github.com/nestjs/azure-database and modified to work only with Azure Cosmos DB.
**The credit goes to the original author.**
### For Azure Cosmos DB support
1. Create or update your existing `.env` file with the following content:
```
AZURE_COSMOS_DB_NAME=
AZURE_COSMOS_DB_ENDPOINT=
AZURE_COSMOS_DB_KEY=
```
2. **IMPORTANT: Make sure to add your `.env` file to your .gitignore! The `.env` file MUST NOT be versioned on Git.**
3. Make sure to include the following call to your main file:
```typescript
if (process.env.NODE_ENV !== 'production') require('dotenv').config();
```
> This line must be added before any other imports!
### Example
> Note: Check out the CosmosDB example project included in the [sample folder](https://github.com/nestjs/azure-database/tree/master/sample/cosmos-db)
#### Prepare your entity
0. Create a new feature module, eg. with the nest CLI:
```shell
$ nest generate module event
```
1. Create a Data Transfer Object (DTO) inside a file named `event.dto.ts`:
```typescript
export class EventDTO {
name: string;
type: string;
date: Date;
location: Point;
}
```
2. Create a file called `event.entity.ts` and describe the entity model using the provided decorators:
- `@CosmosPartitionKey(value: string)`: Represents the `PartitionKey` of the entity (**required**).
- `@CosmosDateTime(value?: string)`: For DateTime values.
For instance, the shape of the following entity:
```typescript
import { CosmosPartitionKey, CosmosDateTime, Point } from 'nestjs-azure-database';
@CosmosPartitionKey('type')
export class Event {
id?: string;
type: string;
@CosmosDateTime() createdAt: Date;
location: Point;
}
```
Will be automatically converted to:
```json
{
"type": "Meetup",
"createdAt": "2019-11-15T17:05:25.427Z",
"position": {
"type": "Point",
"coordinates": [2.3522, 48.8566]
}
}
```
3. Import the `AzureCosmosDbModule` inside your Nest feature module `event.module.ts`:
```typescript
import { Module } from '@nestjs/common';
import { AzureCosmosDbModule } from 'nestjs-azure-database';
import { EventController } from './event.controller';
import { EventService } from './event.service';
import { Event } from './event.entity';
@Module({
imports: [
AzureCosmosDbModule.forRoot({
dbName: process.env.AZURE_COSMOS_DB_NAME,
endpoint: process.env.AZURE_COSMOS_DB_ENDPOINT,
key: process.env.AZURE_COSMOS_DB_KEY,
}),
AzureCosmosDbModule.forFeature([{ dto: Event }]),
],
providers: [EventService],
controllers: [EventController],
})
export class EventModule {}
```
#### CRUD operations
0. Create a service that will abstract the CRUD operations:
```shell
$ nest generate service event
```
1. 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:
```typescript
import { Injectable } from '@nestjs/common';
import { InjectModel } from 'nestjs-azure-database';
import { Event } from './event.entity';
@Injectable()
export class EventService {
constructor(
@InjectModel(Event)
private readonly eventContainer,
) {}
}
```
The Azure Cosmos DB `Container` provides a couple of public APIs and Interfaces for managing various CRUD operations:
##### CREATE
`create(entity: T): Promise`: creates a new entity.
```typescript
@Post()
async create(event: Event): Promise {
return this.eventContainer.items.create(event)
}
```
##### READ
`query(query: string | SqlQuerySpec, options?: FeedOptions): QueryIterator`: run a SQL Query to find a document.
```typescript
@Get(':id')
async getContact(@Param('id') id) {
try {
const querySpec = {
query: "SELECT * FROM root r WHERE r.id=@id",
parameters: [
{
name: "@id",
value: id
}
]
};
const { resources } = await this.eventContainer.items.query(querySpec).fetchAll()
return resources
} catch (error) {
// Entity not found
throw new UnprocessableEntityException(error);
}
}
```
##### UPDATE
`read(options?: RequestOptions): Promise>`: Get a document.
`replace(body: T, options?: RequestOptions): Promise>`: Updates a document.
```typescript
@Put(':id')
async saveEvent(@Param('id') id, @Body() eventData: EventDTO) {
try {
const { resource: item } = await this.eventContainer.item(id, 'type').read()
// Disclaimer: Assign only the properties you are expecting!
Object.assign(item, eventData);
const { resource: replaced } = await this.eventContainer
.item(id, 'type')
.replace(item)
return replaced
} catch (error) {
throw new UnprocessableEntityException(error);
}
}
```
##### DELETE
`delete(options?: RequestOptions): Promise>`: Removes an entity from the database.
```typescript
@Delete(':id')
async deleteEvent(@Param('id') id) {
try {
const { resource: deleted } = await this.eventContainer
.item(id, 'type')
.delete()
return deleted;
} catch (error) {
throw new UnprocessableEntityException(error);
}
}
```
## Support
Nest is an MIT-licensed open source project.
## License
Nest is [MIT licensed](LICENSE).
[edm-types]: http://bit.ly/nest-edm
---
_Source: https://npm.io/package/nestjs-azure-cosmos · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._