Standard Component Compose Framework (TypeScript)

TypeScript implementation of Standard Component Compose Framework providing standardized component encapsulation and message dispatch engine.

📦 Features

• Standardized Component Encapsulation Protocol: Clean separation between outer (interface/protocol) and inner (implementation) layers
• Flexible Message Dispatch Engine: 7 different routing strategies that can be combined
• Type-Safe Actor Pattern: Similar to Akka Actor but simplified and type-safe
• Generic Path Routing: Support for Ant-style path patterns with variable extraction
• Zero Dependencies: Pure TypeScript implementation with no runtime dependencies

🏗️ Architecture

Core Modules

1. Component Package (src/component)

Standardized component encapsulation following Data-Oriented Programming principles:

import { runByFuncStyleAdapter } from 'depa-processor';

const result = runByFuncStyleAdapter(
  runtime,
  input,
  config,
  outerDerivedAdapter,
  innerRuntimeAdapter,
  innerInputAdapter,
  innerConfigAdapter,
  coreLogicAdapter,
  outputAdapter
);

Manifest Protocol

depa-processor 现在同时提供正式的组件声明与分发协议：

• createComponentManifest(...)
• createComponentVariantManifest(...)
• createComponentBundleManifest(...)
• ManifestRegistryComposer

这套协议的目标不是消灭目录级 index.ts，而是让 index.ts 成为正式的 manifest authoring layer。一个组件目录现在可以：

• 显式决定导出哪些组件
• 同时导出多个变体
• 为不同变体绑定不同 prompt / schema / config
• 把多个目录 manifest 组合成 bundle，再交给上层 registry 或 route 层消费

最小示例：

import {
  createComponentManifest,
  createComponentVariantManifest,
  ManifestRegistryComposer,
} from "depa-processor";

const taskTreeWriteVariants = createComponentVariantManifest({
  baseId: "aiagent.tool.tasktree-write",
  defaultVariant: "tree",
  variants: {
    tree: createComponentManifest({
      id: "aiagent.tool.tasktree-write.tree",
      kind: "tool",
      exportName: "TaskTreeWrite",
      build: () => buildTreeToolDef(),
      meta: { routeKey: "tool.tasktree.write.tree" },
    }),
    flat: createComponentManifest({
      id: "aiagent.tool.tasktree-write.flat",
      kind: "tool",
      exportName: "TaskTreeWriteFlat",
      build: () => buildFlatToolDef(),
      meta: { routeKey: "tool.tasktree.write.flat" },
    }),
  },
});

const defaultToolDefs = ManifestRegistryComposer.composeToolDefs([taskTreeWriteVariants]);
const allVariantToolDefs = ManifestRegistryComposer.composeToolDefs([taskTreeWriteVariants], {
  resolveMode: "all",
});

2. Dispatch Package (src/dispatch)

Central message dispatch engine supporting 7 strategies:

• CLASS: Dispatch by object constructor type
• ROUTE_KEY: Dispatch by string route key
• ENUM: Dispatch by enum value
• ROUTE_KEY_TO_ENUM: Convert route key to enum, then dispatch
• COMMAND_TABLE: CommandTable pattern (string → enum → handler)
• PATH: Dispatch by path pattern (Ant-style wildcards)
• ACTION_PATH: Dispatch by action + path combination

import { DispatchEngine, DispatchStrategyConfig } from 'depa-processor';

const engine = new DispatchEngine<Response>();

engine
  .registerStrategy(DispatchStrategyConfig.forClassStrategy({
    handlerMap: classHandlers,
    defaultHandler: fallbackHandler
  }))
  .registerStrategy(DispatchStrategyConfig.forRouteKeyStrategy({
    handlerMap: keyHandlers,
    defaultKeyHandler: defaultKeyHandler
  }));

const result = engine.dispatch(request);

3. Router Package (src/router)

Generic routers for path-based and action+path dispatch:

import { GenericPathRouter } from 'depa-processor';

const router = new GenericPathRouter<Runtime, Request, Response>(
  (req) => req.path
);

router
  .register('/users/{id}', (runtime, request, match) => {
    const userId = match.variables['id'];
    return { userId, data: getUserById(userId) };
  })
  .register('/users/**', (runtime, request, match) => {
    return { data: getAllUsers() };
  });

const response = router.dispatch(runtime, request);

4. Actor Package (src/actor)

Type-safe Actor pattern with multiple dispatch mechanisms:

import { AbstractActor, ActorRouteBuilder } from 'depa-processor';

class UserApi extends AbstractActor<Result<any>> {
  protected createActorRoute() {
    return ActorRouteBuilder.create<Result<any>>()
      .match(
        SearchRequest,
        new Set(['search', 'searchUsers']),
        new Set([UserApiKey.SEARCH]),
        (req) => this.handleSearch(req)
      )
      .registerEnumConverter('UserApiKey', (key) =>
        UserApiKey[key.toUpperCase() as keyof typeof UserApiKey]
      )
      .build();
  }

  protected createErrorResult(msg: string) {
    return Result.fail(msg);
  }
}

const api = new UserApi();

// Dispatch by class
api.call(new SearchRequest('john'));

// Dispatch by route key
api.callByRouteKey('search', { keyword: 'john' });

// Dispatch by enum
api.callByEnum(UserApiKey.SEARCH, { keyword: 'john' });

// CommandTable pattern
api.callByCommand('SEARCH', { keyword: 'john' });

📊 Dispatch Strategies Comparison

| Strategy | Use Case | Example | |----------|----------|---------| | CLASS | Type-based routing | HTTP request objects | | ROUTE_KEY | String-based routing | REST API endpoints | | ENUM | Enum-based routing | Command types | | ROUTE_KEY_TO_ENUM | Auto-convert strings to enums | Flexible API | | COMMAND_TABLE | Command pattern | CLI applications | | PATH | Path pattern matching | URL routing | | ACTION_PATH | HTTP method + path | RESTful APIs |

🚀 Installation

npm install depa-processor

🧪 Testing

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode
npm run test:watch

Test Results: 137 tests passing ✅

📝 TypeScript Support

Full TypeScript support with comprehensive type definitions:

import type {
  StdInnerLogic,
  DispatchEngine,
  IActor,
  GenericPathRouter
} from 'depa-processor';

🏛️ Design Principles

1. Data-Oriented Programming: Focus on data transformation rather than object hierarchies
2. Type Safety: Leverage TypeScript's type system for compile-time safety
3. Separation of Concerns: Clear separation between outer (protocol) and inner (implementation) layers
4. Flexibility: Multiple dispatch strategies that can be combined
5. Zero Dependencies: Pure TypeScript implementation

📖 Documentation

For detailed documentation, see the Java version documentation at: /Users/kongweixian/solution/aip-system/depa-processor/

This repository also contains the first real variant adoption in:

• cell/packages/organ-logic/src/composer/AIAgent/tools/TaskTreeRead
• cell/packages/organ-logic/src/composer/AIAgent/tools/TaskTreeWrite

🔄 Migration from Java

This TypeScript version maintains the core design and API from the Java version while taking advantage of TypeScript's features:

• Function types instead of functional interfaces
• Type unions and intersections for flexible typing
• Optional chaining and nullish coalescing
• Modern ES2020+ features

🛠️ Build

# Build the project
npm run build

# Clean build artifacts
npm run clean

📦 Project Structure

depa-processor.ts/
├── src/
│   ├── component/           # Standardized component protocol
│   ├── dispatch/            # Message dispatch engine
│   ├── router/              # Generic routers
│   ├── actor/               # Actor pattern
│   └── index.ts            # Main exports
├── dist/                    # Compiled output
├── package.json
├── tsconfig.json
└── jest.config.js

📄 License

MIT

👤 Author

kongweixian

Version: 0.4.0 Language: TypeScript 5.3+ Node: >=14.0.0