@permas/database-adapter NPM

@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

# 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

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.