@simplysm/service-common 13.0.100 → 14.0.4

package/docs/protocol.md

@@ -1,252 +0,0 @@
-# Protocol
-
-## `PROTOCOL_CONFIG`
-
-Service protocol configuration constants.
-
-```typescript
-const PROTOCOL_CONFIG = {
-  MAX_TOTAL_SIZE: 100 * 1024 * 1024,     // Max message size (100MB)
-  SPLIT_MESSAGE_SIZE: 3 * 1024 * 1024,   // Chunking threshold (3MB)
-  CHUNK_SIZE: 300 * 1024,                 // Chunk size (300KB)
-  GC_INTERVAL: 10 * 1000,                // GC interval (10s)
-  EXPIRE_TIME: 60 * 1000,                // Incomplete message expiry (60s)
-} as const;
-```
-
-## `ServiceProtocol`
-
-Service protocol interface for encoding/decoding binary messages.
-
-```typescript
-interface ServiceProtocol {
-  encode(uuid: string, message: ServiceMessage): { chunks: Bytes[]; totalSize: number };
-  decode<T extends ServiceMessage>(bytes: Bytes): ServiceMessageDecodeResult<T>;
-  dispose(): void;
-}
-```
-
-| Method | Description |
-|--------|-------------|
-| `encode()` | Encode a message (auto-split if exceeding 3MB) |
-| `decode()` | Decode a message (auto-reassemble chunked packets) |
-| `dispose()` | Release GC timer and free memory |
-
-## `ServiceMessageDecodeResult`
-
-Message decode result type (union).
-
-```typescript
-type ServiceMessageDecodeResult<TMessage extends ServiceMessage> =
-  | { type: "complete"; uuid: string; message: TMessage }
-  | { type: "progress"; uuid: string; totalSize: number; completedSize: number };
-```
-
-## `createServiceProtocol`
-
-Create a service protocol encoder/decoder. Binary Protocol V2: Header 28 bytes (UUID 16 + TotalSize 8 + Index 4) + JSON body. Auto chunking at 300KB when exceeding 3MB. Max 100MB.
-
-```typescript
-function createServiceProtocol(): ServiceProtocol;
-```
-
-## `ServiceMessage`
-
-Union type of all service messages.
-
-```typescript
-type ServiceMessage =
-  | ServiceReloadMessage
-  | ServiceRequestMessage
-  | ServiceAuthMessage
-  | ServiceProgressMessage
-  | ServiceResponseMessage
-  | ServiceErrorMessage
-  | ServiceAddEventListenerMessage
-  | ServiceRemoveEventListenerMessage
-  | ServiceGetEventListenerInfosMessage
-  | ServiceEmitEventMessage
-  | ServiceEventMessage;
-```
-
-## `ServiceServerMessage`
-
-Messages sent from server to client.
-
-```typescript
-type ServiceServerMessage =
-  | ServiceReloadMessage
-  | ServiceResponseMessage
-  | ServiceErrorMessage
-  | ServiceEventMessage;
-```
-
-## `ServiceServerRawMessage`
-
-Server messages including progress notifications.
-
-```typescript
-type ServiceServerRawMessage = ServiceProgressMessage | ServiceServerMessage;
-```
-
-## `ServiceClientMessage`
-
-Messages sent from client to server.
-
-```typescript
-type ServiceClientMessage =
-  | ServiceRequestMessage
-  | ServiceAuthMessage
-  | ServiceAddEventListenerMessage
-  | ServiceRemoveEventListenerMessage
-  | ServiceGetEventListenerInfosMessage
-  | ServiceEmitEventMessage;
-```
-
-## `ServiceReloadMessage`
-
-Server reload command to client.
-
-```typescript
-interface ServiceReloadMessage {
-  name: "reload";
-  body: {
-    clientName: string | undefined;
-    changedFileSet: Set<string>;
-  };
-}
-```
-
-## `ServiceProgressMessage`
-
-Server progress notification for chunked messages.
-
-```typescript
-interface ServiceProgressMessage {
-  name: "progress";
-  body: {
-    totalSize: number;
-    completedSize: number;
-  };
-}
-```
-
-## `ServiceErrorMessage`
-
-Server error notification.
-
-```typescript
-interface ServiceErrorMessage {
-  name: "error";
-  body: {
-    name: string;
-    message: string;
-    code: string;
-    stack?: string;
-    detail?: unknown;
-    cause?: unknown;
-  };
-}
-```
-
-## `ServiceAuthMessage`
-
-Client authentication message.
-
-```typescript
-interface ServiceAuthMessage {
-  name: "auth";
-  body: string;
-}
-```
-
-## `ServiceRequestMessage`
-
-Client service method request.
-
-```typescript
-interface ServiceRequestMessage {
-  name: `${string}.${string}`;
-  body: unknown[];
-}
-```
-
-## `ServiceResponseMessage`
-
-Server service method response.
-
-```typescript
-interface ServiceResponseMessage {
-  name: "response";
-  body?: unknown;
-}
-```
-
-## `ServiceAddEventListenerMessage`
-
-Client add event listener request.
-
-```typescript
-interface ServiceAddEventListenerMessage {
-  name: "evt:add";
-  body: {
-    key: string;
-    name: string;
-    info: unknown;
-  };
-}
-```
-
-## `ServiceRemoveEventListenerMessage`
-
-Client remove event listener request.
-
-```typescript
-interface ServiceRemoveEventListenerMessage {
-  name: "evt:remove";
-  body: {
-    key: string;
-  };
-}
-```
-
-## `ServiceGetEventListenerInfosMessage`
-
-Client request for event listener info list.
-
-```typescript
-interface ServiceGetEventListenerInfosMessage {
-  name: "evt:gets";
-  body: {
-    name: string;
-  };
-}
-```
-
-## `ServiceEmitEventMessage`
-
-Client emit event request.
-
-```typescript
-interface ServiceEmitEventMessage {
-  name: "evt:emit";
-  body: {
-    keys: string[];
-    data: unknown;
-  };
-}
-```
-
-## `ServiceEventMessage`
-
-Server event notification.
-
-```typescript
-interface ServiceEventMessage {
-  name: "evt:on";
-  body: {
-    keys: string[];
-    data: unknown;
-  };
-}
-```

package/docs/service-types.md

@@ -1,162 +0,0 @@
-# Service Types
-
-## `OrmService`
-
-ORM service interface. Provides database connection, transaction management, and query execution over the service protocol. Supports MySQL, MSSQL, and PostgreSQL.
-
-```typescript
-interface OrmService {
-  getInfo(opt: DbConnOptions & { configName: string }): Promise<{
-    dialect: Dialect;
-    database?: string;
-    schema?: string;
-  }>;
-  connect(opt: Record<string, unknown>): Promise<number>;
-  close(connId: number): Promise<void>;
-  beginTransaction(connId: number, isolationLevel?: IsolationLevel): Promise<void>;
-  commitTransaction(connId: number): Promise<void>;
-  rollbackTransaction(connId: number): Promise<void>;
-  executeParametrized(connId: number, query: string, params?: unknown[]): Promise<unknown[][]>;
-  executeDefs(connId: number, defs: QueryDef[], options?: (ResultMeta | undefined)[]): Promise<unknown[][]>;
-  bulkInsert(connId: number, tableName: string, columnDefs: Record<string, ColumnMeta>, records: Record<string, unknown>[]): Promise<void>;
-}
-```
-
-| Method | Description |
-|--------|-------------|
-| `getInfo()` | Get database dialect and connection info |
-| `connect()` | Open a new database connection, returns connection ID |
-| `close()` | Close a database connection |
-| `beginTransaction()` | Begin transaction with optional isolation level |
-| `commitTransaction()` | Commit transaction |
-| `rollbackTransaction()` | Rollback transaction |
-| `executeParametrized()` | Execute a parameterized SQL query |
-| `executeDefs()` | Execute QueryDef array |
-| `bulkInsert()` | Bulk insert records |
-
-## `DbConnOptions`
-
-Database connection options.
-
-```typescript
-type DbConnOptions = { configName?: string; config?: Record<string, unknown> };
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `configName` | `string` | Configuration name to look up from server config |
-| `config` | `Record<string, unknown>` | Direct connection config object |
-
-## `AutoUpdateService`
-
-Auto-update service interface. Retrieves the latest version info for client applications.
-
-```typescript
-interface AutoUpdateService {
-  getLastVersion(platform: string): Promise<
-    | { version: string; downloadPath: string }
-    | undefined
-  >;
-}
-```
-
-| Method | Description |
-|--------|-------------|
-| `getLastVersion()` | Retrieve latest version info for a platform (e.g., "win32", "darwin", "android") |
-
-## `SmtpClientSendOption`
-
-Full SMTP send options.
-
-```typescript
-interface SmtpClientSendOption {
-  host: string;
-  port?: number;
-  secure?: boolean;
-  user?: string;
-  pass?: string;
-  from: string;
-  to: string;
-  cc?: string;
-  bcc?: string;
-  subject: string;
-  html: string;
-  attachments?: SmtpClientSendAttachment[];
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `host` | `string` | SMTP server hostname |
-| `port` | `number` | SMTP server port |
-| `secure` | `boolean` | Use TLS |
-| `user` | `string` | SMTP auth username |
-| `pass` | `string` | SMTP auth password |
-| `from` | `string` | Sender email |
-| `to` | `string` | Recipient email |
-| `cc` | `string` | CC recipients |
-| `bcc` | `string` | BCC recipients |
-| `subject` | `string` | Email subject |
-| `html` | `string` | Email body (HTML) |
-| `attachments` | `SmtpClientSendAttachment[]` | File attachments |
-
-## `SmtpClientSendByDefaultOption`
-
-SMTP send options using default server configuration.
-
-```typescript
-interface SmtpClientSendByDefaultOption {
-  to: string;
-  cc?: string;
-  bcc?: string;
-  subject: string;
-  html: string;
-  attachments?: SmtpClientSendAttachment[];
-}
-```
-
-## `SmtpClientSendAttachment`
-
-Email attachment definition.
-
-```typescript
-interface SmtpClientSendAttachment {
-  filename: string;
-  content?: string | Uint8Array;
-  path?: any;
-  contentType?: string;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `filename` | `string` | Attachment filename |
-| `content` | `string \| Uint8Array` | Inline content |
-| `path` | `any` | File path |
-| `contentType` | `string` | MIME type |
-
-## `SmtpClientDefaultOptions`
-
-Default SMTP client configuration.
-
-```typescript
-interface SmtpClientDefaultOptions {
-  senderName: string;
-  senderEmail?: string;
-  user?: string;
-  pass?: string;
-  host: string;
-  port?: number;
-  secure?: boolean;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `senderName` | `string` | Default sender display name |
-| `senderEmail` | `string` | Default sender email |
-| `user` | `string` | SMTP auth username |
-| `pass` | `string` | SMTP auth password |
-| `host` | `string` | SMTP server hostname |
-| `port` | `number` | SMTP server port |
-| `secure` | `boolean` | Use TLS |

package/src/service-types/smtp-client-service.types.ts

@@ -1,41 +0,0 @@
-export interface SmtpClientSendAttachment {
-  filename: string;
-  content?: string | Uint8Array;
-  path?: any;
-  contentType?: string;
-}
-
-export interface SmtpClientSendByDefaultOption {
-  to: string;
-  cc?: string;
-  bcc?: string;
-  subject: string;
-  html: string;
-  attachments?: SmtpClientSendAttachment[];
-}
-
-export interface SmtpClientSendOption {
-  host: string;
-  port?: number;
-  secure?: boolean;
-  user?: string;
-  pass?: string;
-
-  from: string;
-  to: string;
-  cc?: string;
-  bcc?: string;
-  subject: string;
-  html: string;
-  attachments?: SmtpClientSendAttachment[];
-}
-
-export interface SmtpClientDefaultOptions {
-  senderName: string;
-  senderEmail?: string;
-  user?: string;
-  pass?: string;
-  host: string;
-  port?: number;
-  secure?: boolean;
-}

package/tests/define-event.spec.ts

@@ -1,11 +0,0 @@
-// packages/service-common/tests/define-event.spec.ts
-import { describe, it, expect } from "vitest";
-import { defineEvent } from "@simplysm/service-common";
-
-describe("defineEvent", () => {
-  it("create event definition with given name", () => {
-    const evt = defineEvent<{ channel: string }, string>("OrderUpdated");
-    expect(evt.eventName).toBe("OrderUpdated");
-  });
-
-});

package/tests/protocol/service-protocol.spec.ts

@@ -1,251 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { createServiceProtocol, type ServiceProtocol } from "../../src/protocol/create-service-protocol";
-import type { ServiceMessage } from "../../src/protocol/protocol.types";
-import { Uuid } from "@simplysm/core-common";
-
-describe("ServiceProtocol", () => {
-  let protocol: ServiceProtocol;
-
-  beforeEach(() => {
-    protocol = createServiceProtocol();
-  });
-
-  afterEach(() => {
-    protocol.dispose();
-  });
-
-  describe("Encoding", () => {
-    it("encode single message", () => {
-      const uuid = Uuid.generate().toString();
-      const message: ServiceMessage = { name: "test.method", body: [{ test: "data" }] };
-
-      const result = protocol.encode(uuid, message);
-
-      expect(result.chunks.length).toBe(1);
-      expect(result.totalSize).toBeGreaterThan(0);
-    });
-
-    it("throw error when message exceeds 100MB", () => {
-      const uuid = Uuid.generate().toString();
-      // Generate data larger than 100MB
-      const largeData = "x".repeat(101 * 1024 * 1024);
-      const message: ServiceMessage = { name: "test.method", body: [largeData] };
-
-      expect(() => protocol.encode(uuid, message)).toThrow("Message size exceeds the limit.");
-    });
-  });
-
-  describe("Decoding", () => {
-    it("decode single message", () => {
-      const uuid = Uuid.generate().toString();
-      const message: ServiceMessage = { name: "test.method", body: [{ value: 123 }] };
-
-      const encoded = protocol.encode(uuid, message);
-      const result = protocol.decode(encoded.chunks[0]);
-
-      expect(result.type).toBe("complete");
-      if (result.type === "complete") {
-        expect(result.message.name).toBe("test.method");
-        expect(result.message.body).toEqual([{ value: 123 }]);
-      }
-    });
-
-    it("throw error when buffer size is smaller than header size", () => {
-      const smallBytes = new Uint8Array(20);
-
-      expect(() => protocol.decode(smallBytes)).toThrow("Buffer size is smaller than header size.");
-    });
-
-    it("throw error when decoded message exceeds 100MB", () => {
-      // Manually create header with totalSize exceeding 100MB
-      const headerBytes = new Uint8Array(28);
-      const uuidBytes = new Uuid(Uuid.generate().toString()).toBytes();
-      headerBytes.set(uuidBytes, 0);
-
-      const headerView = new DataView(
-        headerBytes.buffer,
-        headerBytes.byteOffset,
-        headerBytes.byteLength,
-      );
-      headerView.setBigUint64(16, BigInt(101 * 1024 * 1024), false); // 101MB
-      headerView.setUint32(24, 0, false);
-
-      expect(() => protocol.decode(headerBytes)).toThrow("Message size exceeds the limit.");
-    });
-  });
-
-  describe("Chunking", () => {
-    it("chunk message larger than 3MB", () => {
-      const uuid = Uuid.generate().toString();
-      // Create 4MB data
-      const largeData = "x".repeat(4 * 1024 * 1024);
-      const message: ServiceMessage = { name: "test.method", body: [largeData] };
-
-      const result = protocol.encode(uuid, message);
-
-      expect(result.chunks.length).toBeGreaterThan(1);
-    });
-
-    it("assemble chunked message in order", () => {
-      const uuid = Uuid.generate().toString();
-      // 4MB data
-      const largeData = "x".repeat(4 * 1024 * 1024);
-      const message: ServiceMessage = { name: "test.method", body: [largeData] };
-
-      const encoded = protocol.encode(uuid, message);
-      expect(encoded.chunks.length).toBeGreaterThan(1);
-
-      // Decode chunks in order
-      let result!: ReturnType<typeof protocol.decode>;
-      for (let i = 0; i < encoded.chunks.length; i++) {
-        result = protocol.decode(encoded.chunks[i]);
-        if (i < encoded.chunks.length - 1) {
-          expect(result.type).toBe("progress");
-        }
-      }
-
-      expect(result.type).toBe("complete");
-      if (result.type === "complete") {
-        expect(result.message.body).toEqual([largeData]);
-      }
-    });
-
-    it("assemble chunked message in reverse order", () => {
-      const uuid = Uuid.generate().toString();
-      // 4MB data
-      const largeData = "x".repeat(4 * 1024 * 1024);
-      const message: ServiceMessage = { name: "test.method", body: [largeData] };
-
-      const encoded = protocol.encode(uuid, message);
-      const reversedChunks = [...encoded.chunks].reverse();
-
-      // Decode in reverse order
-      let result!: ReturnType<typeof protocol.decode>;
-      for (let i = 0; i < reversedChunks.length; i++) {
-        result = protocol.decode(reversedChunks[i]);
-      }
-
-      // Should complete at the end
-      expect(result.type).toBe("complete");
-      if (result.type === "complete") {
-        expect(result.message.body).toEqual([largeData]);
-      }
-    });
-
-    it("prevent duplicate packets", () => {
-      const uuid = Uuid.generate().toString();
-      // 4MB data
-      const largeData = "x".repeat(4 * 1024 * 1024);
-      const message: ServiceMessage = { name: "test.method", body: [largeData] };
-
-      const encoded = protocol.encode(uuid, message);
-
-      // Send first chunk twice
-      protocol.decode(encoded.chunks[0]);
-      const result1 = protocol.decode(encoded.chunks[0]); // Duplicate
-
-      // Should be in progress state, and completedSize should not increase from duplicate
-      expect(result1.type).toBe("progress");
-
-      // Send remaining chunks
-      let result!: ReturnType<typeof protocol.decode>;
-      for (let i = 1; i < encoded.chunks.length; i++) {
-        result = protocol.decode(encoded.chunks[i]);
-      }
-
-      expect(result.type).toBe("complete");
-      if (result.type === "complete") {
-        expect(result.message.body).toEqual([largeData]);
-      }
-    });
-  });
-
-  describe("UUID interleaving", () => {
-    it("receive chunks from multiple UUIDs in interleaved order", () => {
-      const uuid1 = Uuid.generate().toString();
-      const uuid2 = Uuid.generate().toString();
-
-      // Each with 4MB data to trigger chunking
-      const largeData1 = "A".repeat(4 * 1024 * 1024);
-      const largeData2 = "B".repeat(4 * 1024 * 1024);
-      const message1: ServiceMessage = { name: "test.method1", body: [largeData1] };
-      const message2: ServiceMessage = { name: "test.method2", body: [largeData2] };
-
-      const encoded1 = protocol.encode(uuid1, message1);
-      const encoded2 = protocol.encode(uuid2, message2);
-
-      expect(encoded1.chunks.length).toBeGreaterThan(1);
-      expect(encoded2.chunks.length).toBeGreaterThan(1);
-
-      // Decode chunks in interleaved order (uuid1[0], uuid2[0], uuid1[1], uuid2[1], ...)
-      const maxChunks = Math.max(encoded1.chunks.length, encoded2.chunks.length);
-      let result1!: ReturnType<typeof protocol.decode>;
-      let result2!: ReturnType<typeof protocol.decode>;
-
-      for (let i = 0; i < maxChunks; i++) {
-        if (i < encoded1.chunks.length) {
-          result1 = protocol.decode(encoded1.chunks[i]);
-        }
-        if (i < encoded2.chunks.length) {
-          result2 = protocol.decode(encoded2.chunks[i]);
-        }
-      }
-
-      // Both messages should complete
-      expect(result1.type).toBe("complete");
-      expect(result2.type).toBe("complete");
-
-      if (result1.type === "complete" && result2.type === "complete") {
-        expect(result1.message.name).toBe("test.method1");
-        expect(result1.message.body).toEqual([largeData1]);
-        expect(result2.message.name).toBe("test.method2");
-        expect(result2.message.body).toEqual([largeData2]);
-      }
-    });
-
-  });
-
-  describe("Edge cases", () => {
-    it("handle null body", () => {
-      const uuid = Uuid.generate().toString();
-      const message: ServiceMessage = { name: "test.method", body: [null] };
-
-      const encoded = protocol.encode(uuid, message);
-      const decoded = protocol.decode(encoded.chunks[0]);
-
-      expect(decoded.type).toBe("complete");
-      if (decoded.type === "complete") {
-        // JsonConvert.stringify/parse converts null to undefined
-        expect(decoded.message.body).toEqual([undefined]);
-      }
-    });
-
-    it("handle message at exactly 3MB boundary", () => {
-      const uuid = Uuid.generate().toString();
-      // Exactly 3MB
-      const data = "x".repeat(3 * 1024 * 1024 - 50); // Account for some JSON overhead
-      const message: ServiceMessage = { name: "test.method", body: [data] };
-
-      const encoded = protocol.encode(uuid, message);
-      // Messages up to 3MB should not be chunked
-      expect(encoded.chunks.length).toBe(1);
-    });
-
-    it("include correct information in progress response", () => {
-      const uuid = Uuid.generate().toString();
-      const largeData = "x".repeat(4 * 1024 * 1024);
-      const message: ServiceMessage = { name: "test.method", body: [largeData] };
-
-      const encoded = protocol.encode(uuid, message);
-      const result = protocol.decode(encoded.chunks[0]);
-
-      expect(result.type).toBe("progress");
-      if (result.type === "progress") {
-        expect(result.uuid).toBe(uuid);
-        expect(result.totalSize).toBe(encoded.totalSize);
-        expect(result.completedSize).toBeGreaterThan(0);
-        expect(result.completedSize).toBeLessThan(result.totalSize);
-      }
-    });
-  });
-});