@futdevpro/fsm-dynamo

Full Stack Model Collection for Dynamic (NodeJS-TypeScript) Framework

Dynamo FSM (Full Stack Module) is the foundational TypeScript package that provides the core infrastructure and shared utilities for building full-stack applications. It serves as the base structure for all other Dynamo projects, establishing consistent patterns, type definitions, and interfaces that ensure seamless integration between frontend and backend implementations.

Naming Convention: All exports from Dynamo FSM use the DyFM_* prefix (Dynamo Full Stack Module), ensuring clear identification and preventing naming conflicts. This consistent prefix pattern makes it easy to identify FSM utilities, classes, interfaces, and enums throughout your codebase.

Table of Contents

• Introduction
• Features
• Installation
• Quick Start
• Modules
• Common Usage Patterns
• API Reference
• Requirements
• Support & Contributing
• License

Introduction

Dynamo FSM provides core utilities for data manipulation, error handling, logging, state management, and more. It includes modules covering AI integration, real-time communication, location services, data transformation, and testing tools. This package serves as the base structure for all other Dynamo projects.

Naming Convention: All exports from Dynamo FSM use the DyFM_* prefix (Dynamo Full Stack Module). This consistent naming pattern makes it easy to identify FSM utilities, classes, interfaces, enums, and constants throughout your codebase. Examples include DyFM_Array, DyFM_Log, DyFM_Error, DyFM_DataHandler, and DyFM_Metadata.

Dynamo Packages Using FSM

Dynamo FSM is the foundational package used by all other Dynamo packages:

• Dynamo-NTS - Backend framework for Node.js with TypeScript
• Dynamo NGX Models - Model definitions for Angular applications
• Dynamo NGX - Angular framework with Material Design and Tailwind CSS

All these packages build upon Dynamo FSM's core interfaces, types, and utilities, ensuring consistency and type safety across the entire Dynamo ecosystem.

Key Characteristics

• Zero Dependencies: The foundational package has no dependencies (except peer dependencies), making it the base upon which all other Dynamo packages are built
• Type-Safe Full-Stack Development: Shared interfaces and models ensure data structures, API contracts, and business logic remain consistent from database to UI
• Comprehensive Utility Library: Utilities for arrays, strings, dates, UUIDs, error handling, logging, and more
• Modular Architecture: Import only what you need, keeping bundle sizes small while providing access to a comprehensive toolkit

Features

Core Utilities

• Array Manipulation: Advanced array operations with async support (DyFM_Array)
• String Operations: Comprehensive string manipulation utilities (DyFM_String)
• Time & Date: Advanced time manipulation and formatting (DyFM_Time)
• UUID Generation: Secure UUID generation utilities (DyFM_UUID)
• Logging: Advanced logging with customizable styling (DyFM_Log)
• Error Handling: Standardized error handling with configurable severity levels (DyFM_Error)
• Data Transformation: Type-safe cloning and data manipulation utilities

Specialized Modules

• AI Integration: Unified interface for multiple AI providers (OpenAI, Anthropic, Google, Local AI)
• Reactive Data Management: RxJS-based data handlers for single items, lists, and searchable data
• Real-Time Communication: Socket.IO integration for bidirectional communication
• Location Services: Comprehensive geographical data handling with country information
• Messaging System: Unified messaging for user↔user and user↔AI communication
• Data Transformation: Specialized pipes for geographic data, string manipulation, and formatting
• Crypto Utilities: Deterministic encryption/decryption using AES-256-CBC
• Testing Tools: Comprehensive HTTP endpoint testing utilities
• Analytics: User behavior tracking and usage analytics

Installation

npm install @futdevpro/fsm-dynamo

or

pnpm add @futdevpro/fsm-dynamo

Quick Start

Basic Utility Usage

import { DyFM_Array, DyFM_String, DyFM_Log, DyFM_Error, DyFM_ErrorLevel } from '@futdevpro/fsm-dynamo';

// Array operations
const numbers = [1, 2, 3, 4, 5];
const doubled = DyFM_Array.map(numbers, (n) => n * 2);

// String operations
const formatted = DyFM_String.capitalize('hello world'); // "Hello World"

// Logging
DyFM_Log.info('Application started');
DyFM_Log.warn('This is a warning');
DyFM_Log.error('An error occurred');

// Special logging methods
DyFM_Log.H_error('Highlighted error message'); // Highlighted error with visual formatting
DyFM_Log.T_error('Test error message'); // Test error with special formatting

// Error handling
const error = new DyFM_Error({
  errorCode: 'USER_NOT_FOUND',
  message: 'User with ID 123 not found',
  userMessage: 'User not found',
  level: DyFM_ErrorLevel.error
});

// Or use static method for any error type
DyFM_Error.logSimple('Operation failed', error);

Data Handler Example

import { DyFM_DataHandler } from '@futdevpro/fsm-dynamo/data-handler';
import { DyFM_Metadata } from '@futdevpro/fsm-dynamo';

interface User extends DyFM_Metadata {
  name: string;
  email: string;
}

class UserHandler extends DyFM_DataHandler<User> {
  constructor(apiService: any) {
    super({
      name: 'UserHandler',
      get: async (userId: string) => {
        return await apiService.getUser(userId);
      },
      set: async (user: User) => {
        return await apiService.updateUser(user);
      }
    });
  }
}

// Usage
const userHandler = new UserHandler(apiService);
await userHandler.reload('user-123');
userHandler.data$.subscribe(user => {
  console.log('User loaded:', user);
});

AI Module Example

import { DyFM_AI_Provider, DyFM_AI_MessageRole } from '@futdevpro/fsm-dynamo/ai';
import { DyFM_OAI_Model } from '@futdevpro/fsm-dynamo/ai/open-ai';

// Configure AI provider
const aiConfig = {
  provider: DyFM_AI_Provider.OpenAI,
  apiKey: process.env.OPENAI_API_KEY,
  model: DyFM_OAI_Model.gpt_4o_latest
};

// Create AI request
const aiRequest = {
  messages: [
    {
      role: DyFM_AI_MessageRole.user,
      content: 'Hello, how are you?'
    }
  ],
  settings: aiConfig
};

Modules

Dynamo FSM is organized into 12 specialized modules, each providing focused functionality for specific use cases.

1. Main Module

Import: @futdevpro/fsm-dynamo

The core foundation providing essential utilities, constants, enums, and models for state management and data handling.

Key Features:

• Core utilities for array manipulation, logging, string operations, and type-safe data handling
• Constants for times, data sizes, numbers, and global settings
• Enums for error levels, HTTP types, log styles, and more
• Models for error handling, data properties, and service endpoints

Example:

import { 
  DyFM_Array, 
  DyFM_Log, 
  DyFM_Error, 
  DyFM_times,
  DyFM_ErrorLevel 
} from '@futdevpro/fsm-dynamo';

// Use time constants
const oneDay = DyFM_times.day; // 86400000 milliseconds

// Array operations
const result = DyFM_Array.filter([1, 2, 3, 4], n => n > 2);

2. AI Module

Import: @futdevpro/fsm-dynamo/ai

Unified interface for interacting with multiple AI providers (OpenAI, Anthropic, Google, Local AI).

Key Features:

• Standardized models and interfaces for LLM operations
• Embedding support across providers
• Provider capability detection
• Flexible configuration options

Submodules:

• @futdevpro/fsm-dynamo/ai/open-ai - OpenAI-specific implementations
• @futdevpro/fsm-dynamo/ai/anthropic - Anthropic (Claude) implementations
• @futdevpro/fsm-dynamo/ai/google - Google AI implementations
• @futdevpro/fsm-dynamo/ai/local - Local AI implementations

Example:

import { DyFM_AI_Provider, DyFM_AI_MessageRole } from '@futdevpro/fsm-dynamo/ai';
import { DyFM_OAI_Model } from '@futdevpro/fsm-dynamo/ai/open-ai';

const config = {
  provider: DyFM_AI_Provider.OpenAI,
  model: DyFM_OAI_Model.gpt_4o_latest
};

3. Data Handler Module

Import: @futdevpro/fsm-dynamo/data-handler

Reactive data management utilities using RxJS BehaviorSubjects and Observables.

Key Features:

• Automatic loading prevention (prevents multiple simultaneous load calls)
• Post-processing support for data transformation
• Dependency management for dependent data handlers
• Specialized handlers for lists, searchable data, and pagination

Classes:

• DyFM_DataHandler - Base handler for single data items
• DyFM_DataListHandler - Handler for array data
• DyFM_DataSearchHandler - Handler for searchable data with pagination
• DyFM_ListCollectorDataHandler - Handler for list collections within parent objects

Example:

import { DyFM_DataListHandler } from '@futdevpro/fsm-dynamo/data-handler';

const listHandler = new DyFM_DataListHandler({
  name: 'UsersList',
  get: async () => await apiService.getUsers(),
  setItem: async (user) => await apiService.updateUser(user),
  deleteItem: async (userId) => await apiService.deleteUser(userId)
});

listHandler.dataList$.subscribe(users => {
  console.log('Users updated:', users);
});

4. Location Module

Import: @futdevpro/fsm-dynamo/location

Comprehensive suite for handling geographical data and location-based functionality.

Key Features:

• Country information management with ISO codes
• Administrative divisions data
• Geographical utilities for coordinates and distance calculations
• Region classification and IP-based location services
• Phone code integration

Example:

import { 
  DyFM_CountryISOs, 
  DyFM_LocationUtils,
  DyFM_RegionsUtils 
} from '@futdevpro/fsm-dynamo/location';

const country = DyFM_CountryISOs.getByISO('US');
const distance = DyFM_LocationUtils.calculateDistance(
  { lat: 40.7128, lng: -74.0060 },
  { lat: 34.0522, lng: -118.2437 }
);

5. Messaging Module

Import: @futdevpro/fsm-dynamo/messaging

Unified messaging system for user↔user and user↔AI communication.

Key Features:

• Support for direct, group, assistant chat, and channel conversations
• Message types: text, attachments, reactions, mentions, threads
• Real-time capabilities with socket integration
• Agent process visualization for AI reasoning
• Participant role management

Example:

import { 
  DyFM_Msg_Message, 
  DyFM_Msg_Type, 
  DyFM_Msg_Status 
} from '@futdevpro/fsm-dynamo/messaging';

const message = new DyFM_Msg_Message({
  conversationId: 'conv-123',
  senderId: 'user-456',
  content: 'Hello, world!',
  type: DyFM_Msg_Type.text,
  status: DyFM_Msg_Status.sent
});

6. Socket Module

Import: @futdevpro/fsm-dynamo/socket

Real-time bidirectional communication using Socket.IO.

Key Features:

• Event management with predefined event keys
• Client configuration and connection management
• Automatic reconnection logic
• Observable properties for connection and subscription states
• Base service class for custom socket clients

Example:

import { 
  DyFM_SocketClient_ServiceBase,
  DyFM_SocketEvent_Key 
} from '@futdevpro/fsm-dynamo/socket';

class MySocketClient extends DyFM_SocketClient_ServiceBase {
  // Implementation
}

7. Pipe Module

Import: @futdevpro/fsm-dynamo/pipe

Data transformation utilities for manipulating and formatting data.

Key Features:

• Specialized pipes for geographic data, string manipulation, and data formatting
• UI component support with Angular pipe integration
• Multi-pipe functionality for complex transformations
• Country, region, and division formatting

Example:

import { DyFM_pipeTransforms } from '@futdevpro/fsm-dynamo/pipe';

const formatted = DyFM_pipeTransforms.country('US'); // "United States"

8. Crypto Module

Import: @futdevpro/fsm-dynamo/crypto

Deterministic encryption and decryption utilities using AES-256-CBC.

Key Features:

• Deterministic encryption (same input + key = same output)
• Cross-platform compatibility
• URL-safe base64 encoding
• Secure random key generation

Important: This implementation produces identical encrypted output for identical input data and key. Use when consistency across systems is more important than cryptographic security.

Example:

import { DyFM_Crypto } from '@futdevpro/fsm-dynamo/crypto';

const encrypted = DyFM_Crypto.encrypt('sensitive data', 'my-secret-key');
const decrypted = DyFM_Crypto.decrypt(encrypted, 'my-secret-key');

9. Custom Data Module

Import: @futdevpro/fsm-dynamo/custom-data

Flexible storage and management of custom data with metadata support.

Key Features:

• Type-safe data containers with validation rules
• RESTful API endpoints for data operations
• Metadata support for tracking and organization

Example:

import { DyFM_CustomData } from '@futdevpro/fsm-dynamo/custom-data';

const customData = new DyFM_CustomData({
  key: 'user-preferences',
  value: { theme: 'dark', language: 'en' },
  __createdBy: 'user-123'
});

10. Test Module

Import: @futdevpro/fsm-dynamo/test

Comprehensive testing tools for HTTP endpoints.

Key Features:

• Complete suite of HTTP method test endpoints
• Server status monitoring
• Structured response handling

11. Usage Module

Import: @futdevpro/fsm-dynamo/usage

User behavior tracking and analytics tools.

Key Features:

• Session management
• Usage analytics and geographic insights
• Daily statistics and action tracking

Example:

import { DyFM_UsageSession } from '@futdevpro/fsm-dynamo/usage';

const session = new DyFM_UsageSession({
  userId: 'user-123',
  startTime: new Date(),
  __createdBy: 'system'
});

12. CI Tools Module

Import: @futdevpro/fsm-dynamo/ci-tools

Models and enums for tracking CI/CD pipeline results.

Key Features:

• Build, test, and deployment pipeline tracking
• Detailed step-by-step results
• Result code enums for standardized status reporting

Example:

import { 
  DyFM_CIT_CIResultCode,
  DyFM_CIT_CIResultInfo 
} from '@futdevpro/fsm-dynamo/ci-tools';

const ciResult: DyFM_CIT_CIResultInfo = {
  resultCode: DyFM_CIT_CIResultCode.success,
  // ... other properties
};

Common Usage Patterns

Import Patterns

All exports use the DyFM_ prefix (Dynamo Full Stack Module):

// Main module
import { DyFM_Array, DyFM_Log, DyFM_Error } from '@futdevpro/fsm-dynamo';

// Specific modules
import { DyFM_DataHandler } from '@futdevpro/fsm-dynamo/data-handler';
import { DyFM_AI_Provider } from '@futdevpro/fsm-dynamo/ai';
import { DyFM_Crypto } from '@futdevpro/fsm-dynamo/crypto';

Type Safety

Dynamo FSM provides full TypeScript support with strict typing:

import { DyFM_Metadata, DyFM_Error, DyFM_ErrorLevel } from '@futdevpro/fsm-dynamo';

interface User extends DyFM_Metadata {
  name: string;
  email: string;
}

// Type-safe error handling
const error = new DyFM_Error({
  errorCode: 'VALIDATION_ERROR',
  message: 'Invalid user data',
  level: DyFM_ErrorLevel.warning
});

Error Handling Pattern

import { DyFM_Error, DyFM_ErrorLevel, DyFM_Log } from '@futdevpro/fsm-dynamo';

try {
  // Your code
} catch (err) {
  if (err instanceof DyFM_Error && err.___handled) {
    // Error already handled
    return;
  }
  
  const error = new DyFM_Error({
    errorCode: 'OPERATION_FAILED',
    message: err.message,
    userMessage: 'An error occurred',
    level: DyFM_ErrorLevel.error
  });
  
  // Use logSimple for formatted error logging
  error.logSimple('Operation failed');
  // Or use static method
  DyFM_Error.logSimple('Operation failed', error);
  
  throw error;
}

Special Logging Methods

Dynamo FSM provides specialized logging methods for different use cases:

import { DyFM_Log, DyFM_Error } from '@futdevpro/fsm-dynamo';

// Highlighted error - displays error with visual formatting
DyFM_Log.H_error('Critical error occurred', errorDetails);
// Alias: DyFM_Log.highlightedError()

// Test error - displays error with test-specific formatting
DyFM_Log.T_error('Test error message', testData);
// Alias: DyFM_Log.testError()

// Simple error logging - formatted error output with error code, message, stack
const error = new DyFM_Error({
  errorCode: 'VALIDATION_ERROR',
  message: 'Invalid input',
  level: DyFM_ErrorLevel.error
});

// Static method for any error type
DyFM_Error.logSimple('Operation failed', error);
// Works with both DyFM_Error instances and regular Error objects

Constants Usage

import { DyFM_times, DyFM_data_sizes, DyFM_numbers } from '@futdevpro/fsm-dynamo';

// Time constants
const oneHour = DyFM_times.hour;
const oneDay = DyFM_times.day;
const oneWeek = DyFM_times.week;

// Data size constants
const maxStringLength = DyFM_data_sizes.maxStringLength;

// Number constants
const maxSafeInteger = DyFM_numbers.maxSafeInteger;

API Reference

Main Exports

The main module exports utilities, constants, enums, and models:

Constants:

• DyFM_error_defaults - Default error configuration
• DyFM_global_settings - Global framework settings
• DyFM_numbers - Standard numeric constants
• DyFM_times - Time constants (second, minute, hour, day, week, month, year)
• DyFM_data_sizes - Data size constants

Utilities:

• DyFM_Array - Array manipulation utilities
• DyFM_String - String manipulation utilities
• DyFM_Log - Logging utilities with special methods:
  • DyFM_Log.H_error / DyFM_Log.highlightedError - Big Highlighted error logging
  • DyFM_Log.T_error / DyFM_Log.testError - Mdium Highlighted error logging
  • DyFM_Log.S_error / DyFM_Log.smallError - Small Highlighted error logging
• DyFM_Time - Time manipulation utilities
• DyFM_UUID - UUID generation utilities
• DyFM_Data - Data transformation utilities
• DyFM_Math - Mathematical operations
• DyFM_Random - Random number generation

Enums:

• DyFM_ErrorLevel - Error severity levels
• DyFM_LogStyle - Text styling options
• DyFM_HttpCallType - HTTP request methods
• DyFM_HttpResponseType - HTTP response data types
• DyFM_EnvironmentFlag - Environment types

Models:

• DyFM_Error - Error model with methods:
  • logSimple() - Formatted error logging with error code, message, stack, and additional content
  • static logSimple() - Static method for logging any error type
• DyFM_Metadata - Base metadata model
• DyFM_SearchQuery - Search query interface
• DyFM_SearchResult - Search result interface
• DyFM_Paged - Pagination interface

Module Export Paths

All modules can be imported directly:

// Main module
import { ... } from '@futdevpro/fsm-dynamo';

// Submodules
import { ... } from '@futdevpro/fsm-dynamo/ai';
import { ... } from '@futdevpro/fsm-dynamo/ai/open-ai';
import { ... } from '@futdevpro/fsm-dynamo/ai/anthropic';
import { ... } from '@futdevpro/fsm-dynamo/data-handler';
import { ... } from '@futdevpro/fsm-dynamo/location';
import { ... } from '@futdevpro/fsm-dynamo/messaging';
import { ... } from '@futdevpro/fsm-dynamo/socket';
import { ... } from '@futdevpro/fsm-dynamo/pipe';
import { ... } from '@futdevpro/fsm-dynamo/crypto';
import { ... } from '@futdevpro/fsm-dynamo/custom-data';
import { ... } from '@futdevpro/fsm-dynamo/test';
import { ... } from '@futdevpro/fsm-dynamo/usage';
import { ... } from '@futdevpro/fsm-dynamo/ci-tools';

For detailed API documentation, refer to the Dynamo FSM Documentation.

Requirements

• TypeScript: 5.5.4 or higher
• Node.js: Compatible with Node.js LTS versions
• Peer Dependencies:
  • rxjs: 7.8.1

Support & Contributing

Support

• Donations: https://futdevpro.hu/support/dynamo - Support page for project donations
• Homepage: https://futdevpro.hu/projects/dynamo
• Feedback & Contact: For feature requests, bug reports, or questions, please use the feedback page or contact us at:
  • [email protected]
  • [email protected]

License

MIT License

Copyright (c) Future Development Program Ltd. (HU)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.