Shared Node Architecture Component Kit (SNACK) Blocks

This package provides fundamental building blocks for serverless Node.js applications, focusing on database connectivity and configuration management with AWS integration.

Installation

npm install @timmons-group/snack-blocks

Components

PGDatabaseDriver

A singleton PostgreSQL database driver that provides efficient connection management and query execution for serverless environments.

Features

• Singleton Pattern: Ensures single database connection per application instance
• Connection Pooling: Efficient resource management for serverless functions
• AWS Integration: Works seamlessly with AWS RDS and Aurora
• Error Handling: Comprehensive error management and logging
• SSL Support: Secure connections with configurable SSL options

Usage

Basic Setup with SSM:

import { ConfigurationBuilder, setGlobalConfig, PGDatabaseDriver } from '@timmons-group/snack-blocks';

// Configure database connection using AWS SSM
const config = await new ConfigurationBuilder()
  .withSSM(process.env.SSM_PATH + "connectionString")
  .build();

setGlobalConfig(config);

// Use the database driver
const databaseDriver = new PGDatabaseDriver();
const result = await databaseDriver.query('SELECT * FROM users WHERE id = $1', [userId]);

Setup with Secrets Manager:

import { ConfigurationBuilder, setGlobalConfig } from '@timmons-group/snack-blocks';

const config = await new ConfigurationBuilder()
  .withSecretsManager(process.env.SECRETS_MANAGER_PATH)
  .build();

setGlobalConfig(config);

Manual Configuration:

import { ConfigurationBuilder } from '@timmons-group/snack-blocks';

const config = await new ConfigurationBuilder()
  .withHost('localhost')
  .withPort(5432)
  .withDatabase('myapp')
  .withUser('dbuser')
  .withPassword('password')
  .withSSL(false)
  .withConnectionTimeoutMillis(5000)
  .build();

ConfigurationBuilder

A flexible builder pattern for creating database configuration objects with support for multiple configuration sources.

Configuration Sources

• AWS SSM Parameter Store: Secure parameter storage
• AWS Secrets Manager: Encrypted secrets management
• Connection Strings: Npgsql-format connection strings
• Manual Configuration: Individual parameter setting

Methods

• withSSM(path) - Load configuration from SSM Parameter Store
• withSecretsManager(path) - Load configuration from Secrets Manager
• withConnectionString(connectionString) - Parse Npgsql connection string
• withHost(host) - Set database host
• withPort(port) - Set database port
• withDatabase(database) - Set database name
• withUser(user) - Set database user
• withPassword(password) - Set database password
• withSSL(rejectUnauthorized) - Configure SSL settings
• withConnectionTimeoutMillis(timeout) - Set connection timeout
• build() - Create the configuration object

Connection String Format

The ConfigurationBuilder supports Npgsql-format connection strings:

Server=myhost;Username=myuser;Password=mypass;Database=mydb;Port=5432

Global Configuration

Use the global configuration pattern for consistent database access across your application:

Manual Configuration Setup

// In your setup/initialization file
import { ConfigurationBuilder, setGlobalConfig } from '@timmons-group/snack-blocks';

const config = await new ConfigurationBuilder()
  .withSSM(process.env.SSM_PATH + "connectionString")
  .build();

setGlobalConfig(config);

Configuration File Setup (Recommended for Production)

For deployed environments, create a snack-config.js file and set the SNACK_CONFIG environment variable:

# Environment variable
SNACK_CONFIG=./snack-config.js

# Or use project root alias (requires package.json configuration)
SNACK_CONFIG=@/snack-config.js

Project Root Alias Setup

To use the @/ prefix, configure your package.json with import aliases:

{
  "name": "your-project", 
  "type": "module",
  "imports": {
    "@/*": "./*"
  }
}

Example snack-config.js:

import { ConfigurationBuilder } from '@timmons-group/snack-blocks';

const databaseConfigurationBuilder = new ConfigurationBuilder();
export const databaseConfiguration = await (
    databaseConfigurationBuilder
        .withSSM(process.env.SSM_PATH + "connectionString")
        .build()
);

When SNACK_CONFIG is set, the configuration is automatically loaded at startup.

Using the Configuration

// In your application code
import { PGDatabaseDriver } from '@timmons-group/snack-blocks';

const databaseDriver = new PGDatabaseDriver();
// Configuration is automatically loaded from global config or SNACK_CONFIG file

Environment Variables

• SNACK_CONFIG - Path to configuration file (recommended for production)
• SSM_PATH - Base path for SSM parameters
• SECRETS_MANAGER_PATH - Path to Secrets Manager secret
• LOG_LEVEL - Logging level (ERROR, WARN, INFO)

Best Practices

1. Initialize Early: Set up global configuration at application startup
2. Use AWS Services: Leverage SSM or Secrets Manager for secure credential storage
3. Connection Pooling: The singleton pattern handles connection efficiency
4. Error Handling: Always handle database errors appropriately
5. SSL in Production: Use SSL connections for production databases

Dependencies

• pg - PostgreSQL client library
• @aws-sdk/client-ssm - AWS SSM client
• @aws-sdk/client-secrets-manager - AWS Secrets Manager client
• @timmons-group/snack-utils - Logging utilities

Exports

// Main exports
import { PGDatabaseDriver, ConfigurationBuilder, setGlobalConfig } from '@timmons-group/snack-blocks';

// Individual imports
import PGDatabaseDriver from '@timmons-group/snack-blocks/PGDatabaseDriver';
import { ConfigurationBuilder } from '@timmons-group/snack-blocks/ConfigurationBuilder';

Roadmap

• [x] PostgreSQL database driver
• [x] Configuration builder with AWS integration
• [x] SSL support
• [x] Connection string parsing
• [ ] Connection pooling improvements
• [ ] MySQL support
• [ ] Connection health checks
• [ ] Metrics and monitoring
• [ ] Transaction support