@mbc-cqrs-serverless/core 0.1.49-beta.0 → 0.1.50-beta.0

package/README.md

@@ -1,99 +1,206 @@
 ![MBC CQRS serverless framework](https://mbc-cqrs-serverless.mbc-net.com/img/mbc-cqrs-serverless.png)
 
-# MBC CQRS serverless framework CORE package
+# MBC CQRS serverless framework Core package
 
 ## Description
 
-This is the core package of the MBC CQRS Serverless framework. It provides the basic functionality of CQRS.
+The Core package provides the foundational functionality for the MBC CQRS Serverless framework. It implements:
 
-## Installation
+- Command Query Responsibility Segregation (CQRS) patterns
+- Event-driven architecture support
+- Data persistence and retrieval
+- Authentication and authorization
+- Multi-tenant data isolation
+- AWS service integrations
 
-To install `mbc` command, run:
+## Installation
 
 ```bash
-npm install -g @mbc-cqrs-serverless/cli
+npm install @mbc-cqrs-serverless/core
 ```
 
 ## Usage
 
-### `mbc new|n [projectName@version]`
+### Basic Setup
+
+1. Import and configure the core module:
+```typescript
+import { CoreModule } from '@mbc-cqrs-serverless/core';
+import { Module } from '@nestjs/common';
+
+@Module({
+  imports: [
+    CoreModule.forRoot({
+      region: 'ap-northeast-1',
+      stage: 'dev',
+    }),
+  ],
+})
+export class AppModule {}
+```
 
-There are 3 usages for the new command:
+### Command Handling
+
+1. Create a command:
+```typescript
+import { CommandInputModel } from '@mbc-cqrs-serverless/core';
+
+export class CreateUserCommand implements CommandInputModel {
+  readonly pk: string;
+  readonly sk: string;
+  readonly id: string;
+  
+  constructor(public readonly userId: string, public readonly userData: any) {
+    this.pk = `USER#${userId}`;
+    this.sk = `METADATA#${userId}`;
+    this.id = userId;
+  }
+}
+```
 
-- `mbc new`
-    - Creates a new project in the current folder using a default name with the latest framework version.
-- `mbc new [projectName]`
-    - Creates a new project in the `projectName` folder using the latest framework version.
-- `mbc new [projectName@version]`
-    - If the specified version exists, the CLI uses that exact version.
-    - If the provided version is a prefix, the CLI uses the latest version matching that prefix.
-    - If no matching version is found, the CLI logs an error and provides a list of available versions for the user.
+2. Implement a command handler:
+```typescript
+import { CommandHandler, ICommandHandler } from '@mbc-cqrs-serverless/core';
 
-To change current directory
+@CommandHandler(CreateUserCommand)
+export class CreateUserHandler implements ICommandHandler<CreateUserCommand> {
+  async execute(command: CreateUserCommand): Promise<void> {
+    // Implementation
+  }
+}
+```
 
-```bash
-cd [projectName]
+### Event Handling
+
+1. Create an event handler:
+```typescript
+import { EventsHandler, IEventHandler } from '@mbc-cqrs-serverless/core';
+import { UserCreatedEvent } from './user-created.event';
+
+@EventsHandler(UserCreatedEvent)
+export class UserCreatedHandler implements IEventHandler<UserCreatedEvent> {
+  async handle(event: UserCreatedEvent): Promise<void> {
+    // Implementation
+  }
+}
 ```
 
-## Run the Development Server
-1. Run npm run build to the build project using development mode.
-2. Open in other terminal session and run npm run offline:docker
-3. Open in other terminal session and run npm run migrate to migrate RDS and dynamoDB table
-4. Finally, run npm run offline:sls to start serverless offline mode.
+### Data Access
+
+1. Use the DataService for persistence:
+```typescript
+import { DataService, InjectDataService } from '@mbc-cqrs-serverless/core';
+
+@Injectable()
+export class UserService {
+  constructor(
+    @InjectDataService() private readonly dataService: DataService
+  ) {}
+
+  async getUser(userId: string): Promise<User> {
+    return this.dataService.findOne({
+      pk: `USER#${userId}`,
+      sk: `METADATA#${userId}`,
+    });
+  }
+}
+```
 
-After the server runs successfully, you can see:
+### Authentication & Authorization
+
+1. Implement role-based access:
+```typescript
+import { RolesGuard, Roles } from '@mbc-cqrs-serverless/core';
+
+@Controller('users')
+@UseGuards(RolesGuard)
+export class UserController {
+  @Post()
+  @Roles('admin')
+  async createUser(@Body() userData: CreateUserDto): Promise<void> {
+    // Implementation
+  }
+}
+```
 
-```bash
-DEBUG[serverless-offline-sns][adapter]: successfully subscribed queue "http://localhost:9324/101010101010/notification-queue" to topic: "arn:aws:sns:ap-northeast-1:101010101010:MySnsTopic"
-Offline Lambda Server listening on http://localhost:4000
-serverless-offline-aws-eventbridge :: Plugin ready
-serverless-offline-aws-eventbridge :: Mock server running at port: 4010
-Starting Offline SQS at stage dev (ap-northeast-1)
-Starting Offline Dynamodb Streams at stage dev (ap-northeast-1)
-
-Starting Offline at stage dev (ap-northeast-1)
-
-Offline [http for lambda] listening on http://localhost:3002
-Function names exposed for local invocation by aws-sdk:
-           * main: serverless-example-dev-main
-Configuring JWT Authorization: ANY /{proxy+}
-
-   ┌────────────────────────────────────────────────────────────────────────┐
-   │                                                                        │
-   │   ANY | http://localhost:3000/api/public                               │
-   │   POST | http://localhost:3000/2015-03-31/functions/main/invocations   │
-   │   ANY | http://localhost:3000/swagger-ui/{proxy*}                      │
-   │   POST | http://localhost:3000/2015-03-31/functions/main/invocations   │
-   │   ANY | http://localhost:3000/{proxy*}                                 │
-   │   POST | http://localhost:3000/2015-03-31/functions/main/invocations   │
-   │                                                                        │
-   └────────────────────────────────────────────────────────────────────────┘
-
-Server ready: http://localhost:3000 🚀
+### Multi-tenancy
+
+1. Configure tenant isolation:
+```typescript
+import { TenantContext, UseTenant } from '@mbc-cqrs-serverless/core';
+
+@Injectable()
+export class UserService {
+  @UseTenant()
+  async getUsersForTenant(
+    @TenantContext() tenantId: string
+  ): Promise<User[]> {
+    // Implementation with automatic tenant isolation
+  }
+}
 ```
 
-You can also use several endpoints:
-
-- API gateway: http://localhost:3000
-- Offline Lambda Server: http://localhost:4000
-- HTTP for lambda: http://localhost:3002
-- Step functions: http://localhost:8083
-- DynamoDB: http://localhost:8000
-- DynamoDB admin: http://localhost:8001
-- SNS: http://localhost:4002
-- SQS: http://localhost:9324
-- SQS admin: http://localhost:9325
-- Localstack: http://localhost:4566
-- AppSync: http://localhost:4001
-- Cognito: http://localhost:9229
-- EventBridge: http://localhost:4010
-- Simple Email Service: http://localhost:8005
-- Run `npx prisma studio` to open studio web: http://localhost:5000
+### AWS Integration
+
+1. Use AWS services:
+```typescript
+import { 
+  StepFunctionService, 
+  NotificationService 
+} from '@mbc-cqrs-serverless/core';
+
+@Injectable()
+export class WorkflowService {
+  constructor(
+    private readonly stepFunctions: StepFunctionService,
+    private readonly notifications: NotificationService
+  ) {}
+
+  async startWorkflow(data: any): Promise<void> {
+    await this.stepFunctions.startExecution({
+      stateMachineArn: 'your-state-machine-arn',
+      input: JSON.stringify(data),
+    });
+  }
+}
+```
 
+## Error Handling
+
+The core package provides standardized error handling:
+
+```typescript
+import { 
+  CommandError,
+  ValidationError,
+  NotFoundError 
+} from '@mbc-cqrs-serverless/core';
+
+@CommandHandler(UpdateUserCommand)
+export class UpdateUserHandler implements ICommandHandler<UpdateUserCommand> {
+  async execute(command: UpdateUserCommand): Promise<void> {
+    if (!command.userId) {
+      throw new ValidationError('User ID is required');
+    }
+    
+    const user = await this.userService.findById(command.userId);
+    if (!user) {
+      throw new NotFoundError(`User ${command.userId} not found`);
+    }
+    
+    // Implementation
+  }
+}
+```
 
 ## Documentation
 
-Visit https://mbc-cqrs-serverless.mbc-net.com/ to view the full documentation.
+Visit https://mbc-cqrs-serverless.mbc-net.com/ to view the full documentation, including:
+- Architecture overview
+- Core concepts and patterns
+- AWS integration details
+- Security features
+- API reference
 
 ## License
 

package/dist/helpers/index.d.ts

@@ -2,5 +2,7 @@ export * from './datetime';
 export * from './event-type';
 export * from './key';
 export * from './object';
+export * from './serializer';
 export * from './source';
+export { serializeToExternal, deserializeToInternal } from './serializer';
 export declare const IS_LAMBDA_RUNNING: boolean;

package/dist/helpers/index.js

@@ -14,12 +14,17 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IS_LAMBDA_RUNNING = void 0;
+exports.IS_LAMBDA_RUNNING = exports.deserializeToInternal = exports.serializeToExternal = void 0;
 __exportStar(require("./datetime"), exports);
 __exportStar(require("./event-type"), exports);
 __exportStar(require("./key"), exports);
 __exportStar(require("./object"), exports);
+__exportStar(require("./serializer"), exports);
 __exportStar(require("./source"), exports);
+// Re-export serialization helpers for convenience
+var serializer_1 = require("./serializer");
+Object.defineProperty(exports, "serializeToExternal", { enumerable: true, get: function () { return serializer_1.serializeToExternal; } });
+Object.defineProperty(exports, "deserializeToInternal", { enumerable: true, get: function () { return serializer_1.deserializeToInternal; } });
 exports.IS_LAMBDA_RUNNING = !!process.env.AWS_LAMBDA_FUNCTION_NAME &&
     !!process.env.AWS_LAMBDA_FUNCTION_VERSION &&
     !!process.env.AWS_LAMBDA_FUNCTION_MEMORY_SIZE;

package/dist/helpers/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,6CAA0B;AAC1B,+CAA4B;AAC5B,wCAAqB;AACrB,2CAAwB;AACxB,2CAAwB;AAEX,QAAA,iBAAiB,GAC5B,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB;IACtC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,2BAA2B;IACzC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,+BAA+B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,6CAA0B;AAC1B,+CAA4B;AAC5B,wCAAqB;AACrB,2CAAwB;AACxB,+CAA4B;AAC5B,2CAAwB;AAExB,kDAAkD;AAClD,2CAAyE;AAAhE,iHAAA,mBAAmB,OAAA;AAAE,mHAAA,qBAAqB,OAAA;AAEtC,QAAA,iBAAiB,GAC5B,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB;IACtC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,2BAA2B;IACzC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,+BAA+B,CAAA"}

package/dist/helpers/serializer.d.ts

@@ -0,0 +1,19 @@
+import { CommandEntity, DataEntity } from '../interfaces';
+export interface SerializerOptions {
+    keepAttributes?: boolean;
+    flattenDepth?: number;
+}
+/**
+ * Converts internal DynamoDB structure to external flat structure
+ * @param item Internal item (CommandEntity or DataEntity)
+ * @param options Serialization options
+ * @returns Flattened external structure
+ */
+export declare function serializeToExternal<T extends CommandEntity | DataEntity>(item: T | null | undefined, options?: SerializerOptions): Record<string, any> | null;
+/**
+ * Converts external flat structure to internal DynamoDB structure
+ * @param data External flat structure
+ * @param EntityClass Entity class to instantiate (CommandEntity or DataEntity)
+ * @returns Internal structure
+ */
+export declare function deserializeToInternal<T extends CommandEntity | DataEntity>(data: Record<string, any> | null | undefined, EntityClass: new () => T): T | null;

package/dist/helpers/serializer.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeToExternal = serializeToExternal;
+exports.deserializeToInternal = deserializeToInternal;
+/**
+ * Converts internal DynamoDB structure to external flat structure
+ * @param item Internal item (CommandEntity or DataEntity)
+ * @param options Serialization options
+ * @returns Flattened external structure
+ */
+function serializeToExternal(item, options = {}) {
+    if (!item)
+        return null;
+    const result = {
+        id: `${item.pk}#${item.sk}`,
+        code: item.sk,
+        name: item.name,
+    };
+    // Copy first level properties
+    Object.keys(item).forEach(key => {
+        if (key !== 'attributes' && typeof item[key] !== 'undefined') {
+            result[key] = item[key];
+        }
+    });
+    // Handle attributes
+    if (item.attributes) {
+        Object.entries(item.attributes).forEach(([key, value]) => {
+            result[key] = value;
+        });
+    }
+    return result;
+}
+/**
+ * Converts external flat structure to internal DynamoDB structure
+ * @param data External flat structure
+ * @param EntityClass Entity class to instantiate (CommandEntity or DataEntity)
+ * @returns Internal structure
+ */
+function deserializeToInternal(data, EntityClass) {
+    if (!data)
+        return null;
+    const [pk, sk] = (data.id || '').split('#');
+    const entity = new EntityClass();
+    const attributes = {};
+    // Set basic properties
+    entity.pk = pk;
+    entity.sk = sk || data.code;
+    entity.name = data.name;
+    // Copy entity-specific fields first
+    ['version', 'tenantCode', 'type', 'isDeleted', 'status', 'createdAt', 'updatedAt', 'createdBy', 'updatedBy', 'createdIp', 'updatedIp'].forEach(key => {
+        if (key in data) {
+            entity[key] = data[key];
+        }
+    });
+    // Separate remaining fields into attributes
+    Object.keys(data).forEach(key => {
+        if (!['id', 'code', 'pk', 'sk', 'name', 'version', 'tenantCode', 'type', 'isDeleted', 'status', 'createdAt', 'updatedAt', 'createdBy', 'updatedBy', 'createdIp', 'updatedIp'].includes(key)) {
+            if (key in entity) {
+                entity[key] = data[key];
+            }
+            else {
+                attributes[key] = data[key];
+            }
+        }
+    });
+    entity.attributes = attributes;
+    return entity;
+}
+//# sourceMappingURL=serializer.js.map

package/dist/helpers/serializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializer.js","sourceRoot":"","sources":["../../src/helpers/serializer.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mbc-cqrs-serverless/core",
-  "version": "0.1.49-beta.0",
+  "version": "0.1.50-beta.0",
   "description": "CQRS and event base core",
   "keywords": [
     "mbc",
@@ -15,7 +15,7 @@
     "fargate",
     "step-functions",
     "sqs",
-    "typpescript"
+    "typescript"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -86,5 +86,5 @@
     "serverless-step-functions-local": "^0.5.1",
     "supertest": "^7.0.0"
   },
-  "gitHead": "4fb13a54044022d4423830c985b51dd8ec58259a"
+  "gitHead": "d61475400eb1b00a1c427769875d2f056e48c73c"
 }