@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: '[e-mail]',
    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: '[e-mail]'
  });
  
  // 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