@simplysm/service-common 13.0.98 → 13.0.99

package/README.md

@@ -1,6 +1,8 @@
 # @simplysm/service-common
 
-Service module (common) -- shared protocol and types used by both `@simplysm/service-client` and `@simplysm/service-server`.
+Simplysm package - Service module (common)
+
+Shared protocol and types used by both `@simplysm/service-client` and `@simplysm/service-server`. Provides binary message encoding/decoding, service interface definitions, and event type system.
 
 ## Installation
 
@@ -8,51 +10,102 @@ Service module (common) -- shared protocol and types used by both `@simplysm/ser
 npm install @simplysm/service-common
 ```
 
-## Exports
+## API Overview
+
+### Protocol
+| API | Type | Description |
+|-----|------|-------------|
+| `PROTOCOL_CONFIG` | const | Protocol configuration constants (sizes, timeouts) |
+| `ServiceProtocol` | interface | Binary protocol encoder/decoder interface |
+| `createServiceProtocol` | function | Create a protocol instance |
+| `ServiceMessageDecodeResult` | type | Decode result (complete or progress) |
+| `ServiceMessage` | type | Union of all message types |
+| `ServiceServerMessage` | type | Server-to-client message union |
+| `ServiceServerRawMessage` | type | Server messages including progress |
+| `ServiceClientMessage` | type | Client-to-server message union |
+| `ServiceReloadMessage` | interface | Server reload command |
+| `ServiceProgressMessage` | interface | Chunked message progress notification |
+| `ServiceErrorMessage` | interface | Server error notification |
+| `ServiceAuthMessage` | interface | Client authentication message |
+| `ServiceRequestMessage` | interface | Client service method request |
+| `ServiceResponseMessage` | interface | Server method response |
+| `ServiceAddEventListenerMessage` | interface | Client add event listener |
+| `ServiceRemoveEventListenerMessage` | interface | Client remove event listener |
+| `ServiceGetEventListenerInfosMessage` | interface | Client request event listener infos |
+| `ServiceEmitEventMessage` | interface | Client emit event |
+| `ServiceEventMessage` | interface | Server event notification |
+
+-> See [docs/protocol.md](./docs/protocol.md) for details.
+
+### Service Types
+| API | Type | Description |
+|-----|------|-------------|
+| `OrmService` | interface | ORM service interface (connect, query, transaction) |
+| `DbConnOptions` | type | Database connection options |
+| `AutoUpdateService` | interface | Auto-update service interface |
+| `SmtpClientSendOption` | interface | Full SMTP send options |
+| `SmtpClientSendByDefaultOption` | interface | SMTP send with server defaults |
+| `SmtpClientSendAttachment` | interface | Email attachment definition |
+| `SmtpClientDefaultOptions` | interface | Default SMTP client config |
+
+-> See [docs/service-types.md](./docs/service-types.md) for details.
+
+### Types
+| API | Type | Description |
+|-----|------|-------------|
+| `ServiceUploadResult` | interface | File upload result (path, filename, size) |
+
+-> See [docs/events.md](./docs/events.md) for details.
+
+### Event Definition
+| API | Type | Description |
+|-----|------|-------------|
+| `ServiceEventDef` | interface | Type-safe event definition |
+| `defineEvent` | function | Define a service event with typed info and data |
+
+-> See [docs/events.md](./docs/events.md) for details.
+
+## Usage Examples
+
+### Define and Use Events
 
 ```typescript
-import {
-  // Protocol
-  PROTOCOL_CONFIG,
-  type ServiceMessage,
-  type ServiceServerMessage,
-  type ServiceServerRawMessage,
-  type ServiceClientMessage,
-  type ServiceProtocol,
-  type ServiceMessageDecodeResult,
-  createServiceProtocol,
-  // Service Types
-  type OrmService,
-  type DbConnOptions,
-  type AutoUpdateService,
-  type SmtpClientSendAttachment,
-  type SmtpClientSendByDefaultOption,
-  type SmtpClientSendOption,
-  type SmtpClientDefaultOptions,
-  // Events + Types
-  type ServiceEventDef,
-  defineEvent,
-  type ServiceUploadResult,
-} from "@simplysm/service-common";
+import { defineEvent } from "@simplysm/service-common";
+
+// Define a typed event
+const OrderUpdated = defineEvent<
+  { orderId: number },      // TInfo: filter info
+  { status: string }        // TData: event data
+>("OrderUpdated");
+
+// Server: emit event
+ctx.socket?.emitEvent(OrderUpdated, { orderId: 123 }, { status: "shipped" });
+
+// Client: subscribe to event
+await client.addEventListener(OrderUpdated, { orderId: 123 }, (data) => {
+  console.log(data.status); // typed as string
+});
 ```
 
-## Quick Start
+### Use Protocol
 
 ```typescript
-import { createServiceProtocol, defineEvent } from "@simplysm/service-common";
+import { createServiceProtocol } from "@simplysm/service-common";
 
-// Create protocol encoder/decoder
 const protocol = createServiceProtocol();
-const { chunks, totalSize } = protocol.encode(uuid, { name: "auth", body: token });
-const result = protocol.decode(chunks[0]);
-protocol.dispose();
 
-// Define a typed event
-const OrderUpdated = defineEvent<{ orderId: number }, { status: string }>("OrderUpdated");
-```
+// Encode
+const { chunks, totalSize } = protocol.encode(uuid, {
+  name: "MyService.myMethod",
+  body: [param1, param2],
+});
 
-## Documentation
+// Decode
+const result = protocol.decode(receivedBytes);
+if (result.type === "complete") {
+  handleMessage(result.message);
+}
 
-- [Protocol](docs/protocol.md)
-- [Service Types](docs/service-types.md)
-- [Events and Types](docs/events.md)
+// Cleanup
+protocol.dispose();
+```

package/docs/events.md

@@ -0,0 +1,51 @@
+# Event Definition
+
+## `ServiceEventDef`
+
+Event definition created by `defineEvent()`. `$info` and `$data` are type-only markers (not used at runtime).
+
+```typescript
+interface ServiceEventDef<TInfo = unknown, TData = unknown> {
+  eventName: string;
+  readonly $info: TInfo;
+  readonly $data: TData;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `eventName` | `string` | Event name |
+| `$info` | `TInfo` | Type extraction only (listener filter info type) |
+| `$data` | `TData` | Type extraction only (event data type) |
+
+## `defineEvent`
+
+Define a service event with type-safe info and data.
+
+```typescript
+function defineEvent<TInfo = unknown, TData = unknown>(
+  eventName: string,
+): ServiceEventDef<TInfo, TData>;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `eventName` | `string` | Event name |
+
+## `ServiceUploadResult`
+
+File upload result. Contains information about a file uploaded to the server.
+
+```typescript
+interface ServiceUploadResult {
+  path: string;
+  filename: string;
+  size: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `path` | `string` | Storage path on the server |
+| `filename` | `string` | Original filename |
+| `size` | `number` | File size (bytes) |

package/docs/protocol.md

@@ -0,0 +1,252 @@
+# 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

@@ -0,0 +1,162 @@
+# 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/service-common",
-  "version": "13.0.98",
+  "version": "13.0.99",
   "description": "Simplysm package - Service module (common)",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -14,12 +14,13 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "docs",
     "src",
     "tests"
   ],
   "sideEffects": false,
   "dependencies": {
-    "@simplysm/core-common": "13.0.98",
-    "@simplysm/orm-common": "13.0.98"
+    "@simplysm/core-common": "13.0.99",
+    "@simplysm/orm-common": "13.0.99"
   }
 }