@futdevpro / fsm-dynamo
动态(NodeJS-TypeScript)框架的全栈模型集合
Dynamo FSM (Full Stack Module)是TypeScript的基础包,它为构建全栈应用程序提供了核心基础架构和共享实用程序。它作为所有其他Dynamo项目的基础结构,建立一致的模式、类型定义和接口,以确保前端和后端实现之间的无缝集成。
命名约定:所有从Dynamo FSM导出的文件都使用 DyFM_* 前缀(Dynamo Full Stack Module),确保清晰识别,防止命名冲突。这种一致的前缀模式使得在代码库中识别FSM实用程序、类、接口和枚举变得容易。
目录表
介绍
Dynamo FSM为数据操作、错误处理、日志记录、状态管理等提供了核心实用程序。它包括人工智能集成、实时通信、位置服务、数据转换和测试工具等模块。这个包作为所有其他Dynamo项目的基础结构。
命名约定:所有从Dynamo FSM导出的文件都使用 DyFM_* 前缀(Dynamo全栈模块)。这种一致的命名模式使得在代码库中识别FSM实用程序、类、接口、枚举和常量变得容易。例子包括 DyFM_Array, DyFM_Log, DyFM_Error, DyFM_DataHandler, DyFM_Metadata.
使用FSM的Dynamo包
Dynamo FSM是所有其他Dynamo包使用的基础包:
- Dynamo-NTS -使用TypeScript为Node.js提供后端框架
- 发电机NGX模型 - Angular应用的模型定义
- 发电机NGX - Angular框架与材料设计和顺风CSS
所有这些包都建立在Dynamo FSM的核心接口、类型和实用程序之上,确保了整个Dynamo生态系统的一致性和类型安全性。
关键特性
- 零依赖关系基础包没有依赖关系(除了对等依赖关系),使其成为所有其他Dynamo包构建的基础
- 类型安全的全栈开发共享接口和模型确保从数据库到UI的数据结构、API契约和业务逻辑保持一致
- 综合实用程序库:用于数组、字符串、日期、uuid、错误处理、日志记录等的实用程序
- 模块化的体系结构:只导入需要的内容,保持包的大小较小,同时提供对全面工具包的访问
功能
核心工具
- 数组操作:支持异步的高级数组操作(
DyFM_Array) - 字符串操作:全面的字符串操作实用程序(
DyFM_String) - 时间和日期:高级时间操作和格式设置(
DyFM_Time) - UUID生成:安全UUID生成工具(
DyFM_UUID) - 日志记录:具有可定制样式的高级日志记录(
DyFM_Log) - 错误处理:具有可配置严重级别的标准化错误处理(
DyFM_Error) - 数据转换类型安全的克隆和数据操作实用程序
专业模块
- 人工智能集成:多个AI提供商的统一接口(OpenAI, Anthropic,谷歌,Local AI)
- 响应式数据管理:用于单个项目、列表和可搜索数据的基于rxjs的数据处理程序
- 实时通信:套接字。双向通信的IO集成
- 位置服务:综合地理数据处理与国家信息
- 消息传递系统:用户↔用户和用户↔AI通信的统一消息
- 数据转换:用于地理数据、字符串操作和格式化的专用管道
- 加密工具:使用AES-256-CBC的确定性加密/解密
- 测试工具:全面的HTTP端点测试工具
- 分析用户行为跟踪和使用分析
- 沙箱运行时契约:封闭的跨运行时结果、结果代码和严格的无内容收据验证(
@futdevpro/fsm-dynamo/sandbox-runtime) - 申请提醒合约:完全无内容的警报信封、关闭的严重性/状态、有界整数证据和规范重放校验和(
@futdevpro/fsm-dynamo/application-alert)
安装
npm install @futdevpro/fsm-dynamo
或者
pnpm add @futdevpro/fsm-dynamo
快速入门
基本公用事业使用
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);
数据处理程序示例
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模块示例
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
};
模块
Dynamo FSM被组织成12个专门的模块,每个模块都为特定的用例提供专注的功能。
1. 主模块
进口: @futdevpro/fsm-dynamo
提供用于状态管理和数据处理的基本实用程序、常量、枚举和模型的核心基础。
主要特点:
- 用于数组操作、日志记录、字符串操作和类型安全数据处理的核心实用程序
- 用于时间、数据大小、数字和全局设置的常量
- 错误级别、HTTP类型、日志样式等的枚举
- 错误处理、数据属性和服务端点的模型
例子:
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. 人工智能模块
进口: @futdevpro/fsm-dynamo/ai
用于与多个AI提供商(OpenAI, Anthropic,谷歌,Local AI)交互的统一接口。
主要特点:
- LLM操作的标准化模型和接口
- 跨提供者嵌入支持
- 提供者能力检测
- 灵活的配置选项
子:
@futdevpro/fsm-dynamo/ai/open-ai- openai特定的实现@futdevpro/fsm-dynamo/ai/anthropic-人类(克劳德)的实现@futdevpro/fsm-dynamo/ai/google-谷歌AI实现@futdevpro/fsm-dynamo/ai/local-本地AI实现
例子:
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
};
参见:
- openai兼容的供应商如何操作(LM Studio / Ollama / vLLM / LocalAI) - - - - - -
DyFM_OAI_ClientOptions.baseURL-override mintázattal lokál samass self-hosted LLM-ek
3. 数据处理模块
进口: @futdevpro/fsm-dynamo/data-handler
使用RxJS的BehaviorSubjects和Observables的响应式数据管理工具。
主要特点:
- 自动加载防止(防止多个同时加载调用)
- 数据转换的后处理支持
- 依赖数据处理程序的依赖管理
- 用于列表、可搜索数据和分页的专用处理程序
类:
DyFM_DataHandler-单个数据项的基本处理程序DyFM_DataListHandler-处理数组数据DyFM_DataSearchHandler-处理带有分页的可搜索数据DyFM_ListCollectorDataHandler-父对象中列表集合的处理程序
例子:
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. 位置模块
进口: @futdevpro/fsm-dynamo/location
用于处理地理数据和基于位置的功能的综合套件。
主要特点:
- 国家信息管理与ISO代码
- 行政区划资料
- 坐标和距离计算的地理工具
- 区域分类和基于ip的位置服务
- 电话代码集成
例子:
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. 通讯模块
进口: @futdevpro/fsm-dynamo/messaging
用户↔用户和用户↔AI通信的统一消息传递系统。
主要特点:
- 支持直接、组、助理聊天和频道对话
- 消息类型:文本、附件、回复、提及、线程
- 具有套接字集成的实时功能
- 用于人工智能推理的代理过程可视化
- 参与者角色管理
例子:
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. 套接字模块
进口: @futdevpro/fsm-dynamo/socket
使用Socket.IO进行实时双向通信。
主要特点:
- 带有预定义事件键的事件管理
- 客户端配置和连接管理
- 自动重连接逻辑
- 连接和订阅状态的可观察属性
- 自定义套接字客户端的基本服务类
例子:
import {
DyFM_SocketClient_ServiceBase,
DyFM_SocketEvent_Key
} from '@futdevpro/fsm-dynamo/socket';
class MySocketClient extends DyFM_SocketClient_ServiceBase {
// Implementation
}
7. 管模块
进口: @futdevpro/fsm-dynamo/pipe
用于操作和格式化数据的数据转换实用程序。
主要特点:
- 用于地理数据、字符串操作和数据格式化的专用管道
- UI组件支持Angular管道集成
- 用于复杂转换的多管道功能
- 国家、地区和分区格式
例子:
import { DyFM_pipeTransforms } from '@futdevpro/fsm-dynamo/pipe';
const formatted = DyFM_pipeTransforms.country('US'); // "United States"
8. 加密模块
进口: @futdevpro/fsm-dynamo/crypto
使用AES-256-CBC的确定性加密和解密实用程序。
主要特点:
- 确定性加密(相同输入+密钥=相同输出)
- 跨平台兼容性
- url安全的base64编码
- 安全随机密钥生成
- 跨运行时ECDSA P-256工件签名和公钥验证
- 严格的64字节IEEE P1363签名与无填充Base64URL传输
- 无内容验证码和规范的公共jwk指纹
重要: 该实现为相同的输入数据和密钥生成相同的加密输出。当跨系统的一致性比加密安全性更重要时使用。
例子:
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');
为保证出版物的真实性, DyFM_ArtifactSignature_ControlService 对调用者提供的字节进行符号
pkcs# 8私钥并用一个公开的P-256 JWK进行验证。私有材料属于消费服务器
FDP Keystore配置,并且永远不会在签名证据中返回或发送到浏览器。验证器工作
通过Web Crypto在安全的浏览器环境和支持的Node.js运行时。
部署合同模块
进口: @futdevpro/fsm-dynamo/deployment
FDP操作工具的共享的、无内容的部署目标契约。
主要特点:
- 严格的
fdp-atomic-rollback-manifest/1使用未知字段拒绝进行解析 - 规范的、顺序无关的目标校验和生成
- 不可变的图像引用,摘要和可变的提升目标验证
- 配置修订、兼容性策略和权威证据验证
- 安全的检查后端点验证和有界间隙代码证据
该模块只验证可操作的元数据。应用程序数据、工作簿内容、秘密和凭证则不需要 属于清单,并在作为附加字段提供时被拒绝。
使用 DyFM_AtomicRollbackManifest_Util.validate(value) 对于严格解析和
DyFM_AtomicRollbackManifest_Util.computeTargetChecksum(manifest) 用于规范目标校验和。
9. 自定义数据模块
进口: @futdevpro/fsm-dynamo/custom-data
灵活的自定义数据存储和管理,支持元数据。
主要特点:
- 具有验证规则的类型安全数据容器
- 用于数据操作的RESTful API端点
- 元数据支持跟踪和组织
例子:
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. 测试模块
进口: @futdevpro/fsm-dynamo/test
全面的HTTP端点测试工具。
主要特点:
- 完整的HTTP方法测试端点套件
- 服务器状态监控
- 结构化响应处理
11. 使用模块
进口: @futdevpro/fsm-dynamo/usage
用户行为跟踪和分析工具。
主要特点:
- 会话管理
- 使用分析和地理洞察
- 每日统计和行动跟踪
例子:
import { DyFM_UsageSession } from '@futdevpro/fsm-dynamo/usage';
const session = new DyFM_UsageSession({
userId: 'user-123',
startTime: new Date(),
__createdBy: 'system'
});
12. CI工具模块
进口: @futdevpro/fsm-dynamo/ci-tools
用于跟踪CI/CD管道结果的模型和枚举。
主要特点:
- 构建、测试和部署管道跟踪
- 详细的分步结果
- 用于标准化状态报告的结果代码枚举
例子:
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
};
常用用法模式
导入模式
所有导出都使用 DyFM_ 前缀(Dynamo全栈模块):
// 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';
类型安全
Dynamo FSM通过严格类型提供完整的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
});
错误处理模式
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;
}
特殊测井方法
Dynamo FSM为不同的用例提供了专门的日志记录方法:
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
常量的使用
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参考
主要出口商品
主模块导出实用程序、常量、枚举和模型:
常量:
DyFM_error_defaults-默认错误配置DyFM_global_settings-全局框架设置DyFM_numbers-标准数字常量DyFM_times-时间常数(秒、分、时、日、周、月、年)DyFM_data_sizes-数据大小常量
公用事业:
DyFM_Array-数组操作实用程序DyFM_String-字符串操作实用程序DyFM_Log-具有特殊方法的日志工具:DyFM_Log.H_error/DyFM_Log.highlightedError-大突出显示的错误记录DyFM_Log.T_error/DyFM_Log.testError- medium高亮显示的错误记录DyFM_Log.S_error/DyFM_Log.smallError- Small高亮显示的错误记录
DyFM_Time-时间操作实用程序DyFM_UUID- UUID生成工具DyFM_Data-数据转换实用程序DyFM_Math-数学运算DyFM_Random-随机数生成
枚举:
DyFM_ErrorLevel-错误严重级别DyFM_LogStyle-文本样式选项DyFM_HttpCallType- HTTP请求方法DyFM_HttpResponseType—HTTP响应数据类型DyFM_EnvironmentFlag-环境类型
模型:
DyFM_Error-错误模型与方法:logSimple()-格式化错误日志,包括错误代码、消息、堆栈和附加内容static logSimple()-用于记录任何错误类型的静态方法
DyFM_Metadata-基础元数据模型DyFM_SearchQuery-搜索查询界面DyFM_SearchResult-搜索结果界面DyFM_Paged-分页界面
模块导出路径
所有模块都可以直接导入:
// 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/deployment';
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';
有关详细的API文档,请参阅 Dynamo FSM文档.
要求
- 打印稿: 5.9.3或更高
- node . js:兼容Node.js LTS版本
- 同行依赖性:
rxjs: 7.8.2
支持与贡献
支持
- 捐款: https://futdevpro.hu/support/dynamo -项目捐款支持页面
- 主页: https://futdevpro.hu/projects/dynamo
- 反馈与联系对于功能请求、错误报告或问题,请使用反馈页面或通过以下方式与我们联系:
许可证
MIT许可证
版权所有(c)未来发展计划有限公司
特此向任何获得副本的人免费授予许可 本软件及相关文档文件(“软件”),以处理 不受任何限制,包括但不限于权利 使用、复制、修改、合并、发布、分发、再许可和/或出售 本软件的副本,并允许使用本软件的人 提供这样做,但须符合以下条件:
上述版权声明和本许可声明应包括在所有 本软件的副本或实质性部分。
本软件是“按原样”提供的,没有任何形式的、明示的或明示的保证 默示,包括但不限于对适销性的保证; 适合某一特定目的和不侵权。在任何情况下都不得 作者或版权持有人应对任何索赔、损害赔偿或其他责任 在合同诉讼、侵权诉讼或其他诉讼中,因下列原因引起的责任: 不属于或与本软件或本软件的使用或其他交易有关 软件。