@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.

$3

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.

$3

- 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

$3

- 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

$3

- 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

``bash
npm install @futdevpro/fsm-dynamo
`

or

`bash
pnpm add @futdevpro/fsm-dynamo
`

Quick Start

$3

`typescript
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);
`

$3

`typescript
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 {
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);
});
`

$3

`typescript
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.

$3

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:
`typescript
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);
`

$3

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:
`typescript
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

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:
`typescript
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);
});
`

$3

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:
`typescript
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 }
);
`

$3

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:
`typescript
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
});
`

$3

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:
`typescript
import {
DyFM_SocketClient_ServiceBase,
DyFM_SocketEvent_Key
} from '@futdevpro/fsm-dynamo/socket';

class MySocketClient extends DyFM_SocketClient_ServiceBase {
// Implementation
}
`

$3

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:
`typescript
import { DyFM_pipeTransforms } from '@futdevpro/fsm-dynamo/pipe';

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

$3

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:
`typescript
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');
`

$3

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:
`typescript
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'
});
`

$3

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

$3

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:
`typescript
import { DyFM_UsageSession } from '@futdevpro/fsm-dynamo/usage';

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

$3

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:
`typescript
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

$3

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

`typescript
// 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';
`

$3

Dynamo FSM provides full TypeScript support with strict typing:

`typescript
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
});
`

$3

`typescript
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;
}
`

$3

Dynamo FSM provides specialized logging methods for different use cases:

`typescript
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
`

$3

`typescript
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

$3

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

$3

All modules can be imported directly:

`typescript
// 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

$3

- 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:
- contact@futdevpro.hu
- support@futdevpro.hu

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.