Base Package

The base package provides core framework utilities and shared components that are used across all Dracory projects. It includes theme rendering, CLI infrastructure, database optimizations, and configuration management.

Getting Started
Frontend
Packages
Stores

Base Package

The github.com/dracory/base package provides core framework utilities and shared components that are used across all Dracory projects. It consolidates common functionality to reduce code duplication and ensure consistency across applications.

Installation

go get github.com/dracory/base

Core Components

Theme Rendering

Blog Theme

import "github.com/dracory/base/blogtheme"

// Render paragraph content
html := blogtheme.ParagraphToHtml("Your content here")

// Render headings
html := blogtheme.HeadingToHtml("Title", 1) // h1
html := blogtheme.HeadingToHtml("Subtitle", 2) // h2

// Render images
html := blogtheme.ImageToHtml("src", "alt", "title", "caption")

// Render links
html := blogtheme.LinkToHtml("url", "text", "title")

// Render lists
html := blogtheme.ListToHtml([]string{"Item 1", "Item 2"}, "ordered")

Web Theme

import "github.com/dracory/base/webtheme"

// Render headings
html := webtheme.HeadingToHtml("Title", 1)

// Render paragraphs
html := webtheme.ParagraphToHtml("Content")

// Render code blocks
html := webtheme.CodeToHtml("code", "language")

// Render blockquotes
html := webtheme.BlockquoteToHtml("Quote text", "author")

Blog Blocks

import "github.com/dracory/base/blogblocks"

// Convert JSON blocks to HTML
html := blogblocks.BlocksToHtml(jsonBlocks, options)

CLI Infrastructure

Generic CLI Dispatcher

import "github.com/dracory/base/cli"

// Create type-safe dispatcher for your registry type
dispatcher := cli.NewDispatcher[YourRegistry]()

// Register commands with descriptions and handlers
dispatcher.RegisterCommand("task", "Execute a task by alias", handleTaskCommand)
dispatcher.RegisterCommand("job", "Execute a job with arguments", handleJobCommand)
dispatcher.RegisterCommand("routes", "List all registered routes", handleRoutesCommand)

// Execute commands with automatic lookup and error handling
err := dispatcher.ExecuteCommand(registry, args)

// List all available commands
commands := dispatcher.ListCommands()

// Get specific command
cmd, found := dispatcher.GetCommand("task")

// Check if command exists
hasCmd := dispatcher.HasCommand("task")

// Print usage information
dispatcher.PrintUsage()

Database Utilities

Automatic SQLite Optimizations

import "github.com/dracory/base/database"

// Database package includes automatic optimizations
db, err := database.Open(database.Options{
    Driver: "sqlite",
    DSN:     "database.db",
})

// SQLite optimizations are applied automatically:
// - WAL mode (journal_mode=WAL)
// - NORMAL synchronous mode
// - Foreign keys enforcement
// - 5-second busy timeout
// - Connection pool optimization

Configuration Management

Environment Encryption Loader

import "github.com/dracory/base/config"

// Initialize encrypted environment variables
err := config.InitializeEnvEncVariables(
    "development",           // environment
    "public-key",            // public key
    "private-key",           // private key
    resourceLoader,          // optional embedded resource loader
)

// Enhanced error handling with custom error types
if err != nil {
    switch err.(type) {
    case *config.MissingEnvError:
        // Handle missing environment variables
    case *config.EnvEncError:
        // Handle vault operation failures
    default:
        // Handle other errors
    }
}

HTTP Utilities

Response Body Handling

import "github.com/dracory/base/http"

// Safely close HTTP response body
defer http.SafeCloseResponseBody(resp.Body)

Common Types

Flash Messages

import "github.com/dracory/base/types"

flash := types.FlashMessage{
    Type:    "success",
    Message: "Operation completed successfully",
}

URL Utilities

URL Building

import "github.com/dracory/base/url"

// Build URLs with parameters
url := url.Url("path", "param", "value")

// Get root URL
rootURL := url.RootURL()

// Build query strings
query := url.BuildQuery(map[string]string{
    "key1": "value1",
    "key2": "value2",
})

Migration from Individual Packages

If you were previously using packages that have been moved to base:

From pkg/blogtheme

// Old
import "project/pkg/blogtheme"

// New
import "github.com/dracory/base/blogtheme"

From pkg/webtheme

// Old
import "project/pkg/webtheme"

// New
import "github.com/dracory/base/webtheme"

From pkg/blogblocks

// Old
import "project/pkg/blogblocks"

// New
import "github.com/dracory/base/blogblocks"

Configuration

Environment Variables

The base package supports various environment variables:

# Environment for development/testing/production
APP_ENV=development

# Application name
APP_NAME=MyApp

# Database configuration
DATABASE_DRIVER=sqlite
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=myapp
DATABASE_USER=user
DATABASE_PASSWORD=password
DATABASE_SSL_MODE=require

Encrypted Configuration

Use environment encryption for sensitive data:

# Generate keys
envenc generate-keys

# Create vault
envenc create-vault .env.production.vault

# Add encrypted values
envenc set SECRET_KEY "your-secret-value"
envenc set DATABASE_PASSWORD "db-password"

Integration Patterns

With Registry Pattern

// In your application initialization
import (
    "github.com/dracory/base/cli"
    "github.com/dracory/base/config"
)

func initializeApp() {
    // Load configuration with encryption
    err := config.InitializeEnvEncVariables(
        os.Getenv("APP_ENV"),
        os.Getenv("PUBLIC_KEY"),
        os.Getenv("PRIVATE_KEY"),
        nil,
    )
    
    // Setup CLI dispatcher
    dispatcher := cli.NewDispatcher[registry.RegistryInterface]()
    registerCommands(dispatcher)
}

With Web Applications

// In web handlers
import (
    "github.com/dracory/base/blogtheme"
    "github.com/dracory/base/types"
)

func handleBlogPost(w http.ResponseWriter, r *http.Request) {
    // Use theme rendering
    content := blogtheme.ParagraphToHtml(post.Content)
    
    // Use flash messages
    flash := types.FlashMessage{
        Type:    "info",
        Message: "Post loaded successfully",
    }
    
    // Render response
    fmt.Fprintf(w, "<div class='content'>%s</div>", content)
}

Best Practices

  1. Use Base Components: Always prefer base package components over custom implementations
  2. Environment Encryption: Use encrypted configuration for sensitive data
  3. Type Safety: Leverage the generic CLI dispatcher for type-safe command handling
  4. Database Optimizations: Let the database package handle SQLite optimizations automatically
  5. Error Handling: Use the enhanced error types for better debugging

Version Information

  • Current version: v0.37.0
  • Go version required: 1.25.0+
  • Compatible with all Dracory projects

Support

For additional support: