npm package: @permas/database-adapter
Description: Universal database adapter for PERMAS (Perceptive Focus Management System)
Author: Perceptive Focus, Inc.
Latest version: 0.2.1

# @permas/database-adapter

A universal database adapter for PERMAS (Perceptive Focus Management System). This adapter provides a unified interface to work with various database backends in your PERMAS services.

## Features

- Unified interface to work with multiple database backends:
  - AWS DynamoDB
  - Azure Cosmos DB
  - MongoDB
- Type-safe API with TypeScript
- Consistent API across all database providers
- Core component of PERMAS services
- Peer dependencies approach - only install what you need

## Installation

```bash
# Basic installation
npm install @permas/database-adapter

# If using with DynamoDB
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb @permas/database-adapter

# If using with Azure Cosmos DB
npm install @azure/cosmos @permas/database-adapter

# If using with MongoDB
npm install mongodb @permas/database-adapter
```

## Usage

```typescript
import { createDatabaseAdapter } from '@permas/database-adapter';

// Create a DynamoDB adapter
const dynamoAdapter = createDatabaseAdapter({
  type: 'dynamodb',
  connectionConfig: {
    region: 'us-west-2',
    credentials: {
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
    }
  },
  tableName: 'my-table'
});

// Create a Cosmos DB adapter
const cosmosAdapter = createDatabaseAdapter({
  type: 'cosmosdb',
  connectionConfig: {
    endpoint: process.env.COSMOS_ENDPOINT,
    key: process.env.COSMOS_KEY
  },
  databaseName: 'my-database',
  collectionName: 'my-collection'
});

// Create a MongoDB adapter
const mongoAdapter = createDatabaseAdapter({
  type: 'mongodb',
  connectionConfig: {
    uri: process.env.MONGODB_URI,
    options: { useNewUrlParser: true, useUnifiedTopology: true }
  },
  databaseName: 'my-database',
  collectionName: 'my-collection'
});

// Example operations (same API for all adapters)
async function main() {
  // Connect to the database
  await adapter.connect();
  
  // Create a document
  const newItem = await adapter.create({
    name: 'John Doe',
    email: 'john@example.com',
    active: true
  });
  
  // Find a document by ID
  const item = await adapter.findById(newItem.id);
  
  // Find multiple documents
  const items = await adapter.findMany({
    filter: { active: true },
    limit: 10,
    offset: 0,
    sort: { name: 'asc' }
  });
  
  // Update a document
  const updatedItem = await adapter.update(newItem.id, {
    email: 'john.doe@example.com'
  });
  
  // Delete a document
  const deleted = await adapter.delete(newItem.id);
  
  // Disconnect
  await adapter.disconnect();
}
```

## API Reference

### `createDatabaseAdapter(options)`

Factory function to create a database adapter for the specified type.

### `DatabaseAdapterOptions`

- `type`: Type of database adapter ('dynamodb', 'cosmosdb', or 'mongodb')
- `connectionConfig`: Configuration for the database connection
- `tableName`: Table name for DynamoDB
- `databaseName`: Database name for Cosmos DB and MongoDB
- `collectionName`: Collection name for Cosmos DB and MongoDB

### `DatabaseAdapter` Interface

- `connect()`: Connect to the database
- `disconnect()`: Disconnect from the database
- `create(data)`: Create a new document
- `findById(id)`: Find a document by ID
- `findOne(filter)`: Find a single document matching the filter
- `findMany(options)`: Find multiple documents with optional filtering, sorting, and pagination
- `update(id, data)`: Update a document by ID
- `delete(id)`: Delete a document by ID
- `query(query)`: Execute a raw query against the database

## About PERMAS

PERMAS (Perceptive Focus Management System) is a suite of services provided by Perceptive Focus, Inc. to help businesses manage their data and operations efficiently.

## License

MIT