@lemoncloud/chatic-sockets-lib 0.1.0

package/dist/lib/sockets/packets.d.ts

@@ -0,0 +1,67 @@
+import type { InferSocketError, InferSocketRequest, InferSocketResponse, SocketErrorMessage, SocketRequestMessage, SocketResponseMessage } from '../types';
+declare module '../types' {
+    interface SocketPacketRegistry {
+        'system.ping': {
+            request: null;
+            response: {
+                ts: number;
+            };
+            error: null;
+        };
+        'system.fail': {
+            request: {
+                count?: number;
+            };
+            response: null;
+            error: null;
+        };
+        'demo.echo': {
+            request: {
+                text?: string;
+            };
+            response: {
+                echoed?: string;
+            };
+            error: null;
+        };
+        'demo.route': {
+            request: null;
+            response: {
+                route?: string;
+                kind: 'socket';
+            };
+            error: null;
+        };
+    }
+    interface SocketPacketAliasRegistry {
+        ping: 'system.ping';
+    }
+}
+export declare type SystemPingType = 'system.ping';
+export declare type SystemPingRequestData = InferSocketRequest<SystemPingType>;
+export declare type SystemPingResponseData = InferSocketResponse<SystemPingType>;
+export declare type SystemPingErrorData = InferSocketError<SystemPingType>;
+export declare type SystemPingRequestMessage = SocketRequestMessage<SystemPingType>;
+export declare type SystemPingResponseMessage = SocketResponseMessage<SystemPingType>;
+export declare type SystemPingErrorMessage = SocketErrorMessage<SystemPingType>;
+export declare type SystemFailType = 'system.fail';
+export declare type SystemFailRequestData = InferSocketRequest<SystemFailType>;
+export declare type SystemFailResponseData = InferSocketResponse<SystemFailType>;
+export declare type SystemFailErrorData = InferSocketError<SystemFailType>;
+export declare type SystemFailRequestMessage = SocketRequestMessage<SystemFailType>;
+export declare type SystemFailResponseMessage = SocketResponseMessage<SystemFailType>;
+export declare type SystemFailErrorMessage = SocketErrorMessage<SystemFailType>;
+export declare type DemoEchoType = 'demo.echo';
+export declare type DemoEchoRequestData = InferSocketRequest<DemoEchoType>;
+export declare type DemoEchoResponseData = InferSocketResponse<DemoEchoType>;
+export declare type DemoEchoErrorData = InferSocketError<DemoEchoType>;
+export declare type DemoEchoRequestMessage = SocketRequestMessage<DemoEchoType>;
+export declare type DemoEchoResponseMessage = SocketResponseMessage<DemoEchoType>;
+export declare type DemoEchoErrorMessage = SocketErrorMessage<DemoEchoType>;
+export declare type DemoRouteType = 'demo.route';
+export declare type DemoRouteRequestData = InferSocketRequest<DemoRouteType>;
+export declare type DemoRouteResponseData = InferSocketResponse<DemoRouteType>;
+export declare type DemoRouteErrorData = InferSocketError<DemoRouteType>;
+export declare type DemoRouteRequestMessage = SocketRequestMessage<DemoRouteType>;
+export declare type DemoRouteResponseMessage = SocketResponseMessage<DemoRouteType>;
+export declare type DemoRouteErrorMessage = SocketErrorMessage<DemoRouteType>;

package/dist/lib/sockets/packets.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/lib/types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * `lib/types.ts`
+ * - shared socket packet contracts for both server and client.
+ *
+ * RULES
+ * - every new socket packet type must be registered here first.
+ * - `SocketMessage<T>` payload usage must be derived from this file.
+ * - server/client code should treat this file as the source of truth for packet shapes.
+ */
+/**
+ * common socket message metadata.
+ */
+export interface SocketMessageMeta {
+    /** timestamp (ms) */
+    ts: number;
+    /** extensible metadata bag */
+    [key: string]: unknown;
+}
+/**
+ * base socket message envelope.
+ */
+export interface SocketMessage<T = any, TType extends string = string> {
+    /** message type like `system.ping`, `system.ping:ok`, `system.ping:error` */
+    type: TType;
+    /** payload data */
+    data: T | null;
+    /** request-response correlation id */
+    mid?: string;
+    /** optional metadata */
+    meta?: SocketMessageMeta;
+    /** optional error message */
+    error?: string;
+}
+/**
+ * shared packet registry extension point.
+ *
+ * NOTE
+ * - keep only the base contract here.
+ * - each `src/lib/<domain>/types.ts` can extend this registry via module augmentation.
+ * - response types `:ok` / `:error` are derived from the merged registry.
+ */
+export interface SocketPacketRegistry {
+}
+/**
+ * shorthand alias extension point.
+ * - domain folders can add aliases via module augmentation.
+ */
+export interface SocketPacketAliasRegistry {
+}
+/**
+ * registered request packet type.
+ */
+export declare type SocketPacketType = Extract<keyof SocketPacketRegistry, string>;
+/**
+ * request input type before canonical normalization.
+ */
+export declare type SocketPacketInputType = SocketPacketType | Extract<keyof SocketPacketAliasRegistry, string>;
+/**
+ * resolve shorthand input into canonical packet type.
+ */
+export declare type ResolveSocketPacketType<TType extends SocketPacketInputType> = TType extends keyof SocketPacketAliasRegistry ? SocketPacketAliasRegistry[TType] : TType;
+/**
+ * packet status suffix.
+ */
+export declare type SocketPacketStatus = 'request' | 'ok' | 'error';
+/**
+ * derived success response type.
+ */
+export declare type SocketPacketOkType<TType extends SocketPacketType = SocketPacketType> = `${TType}:ok`;
+/**
+ * derived error response type.
+ */
+export declare type SocketPacketErrorType<TType extends SocketPacketType = SocketPacketType> = `${TType}:error`;
+/**
+ * union of all request/response packet type strings.
+ */
+export declare type SocketMessageType<TType extends SocketPacketType = SocketPacketType> = TType | SocketPacketOkType<TType> | SocketPacketErrorType<TType>;
+/**
+ * request payload of a registered packet.
+ */
+export declare type SocketPacketRequestData<TType extends SocketPacketType> = SocketPacketRegistry[TType]['request'];
+/**
+ * success payload of a registered packet.
+ */
+export declare type SocketPacketResponseData<TType extends SocketPacketType> = SocketPacketRegistry[TType]['response'];
+/**
+ * error payload of a registered packet.
+ */
+export declare type SocketPacketErrorData<TType extends SocketPacketType> = SocketPacketRegistry[TType]['error'];
+/**
+ * typed request message.
+ */
+export declare type SocketRequestMessage<TType extends SocketPacketType = SocketPacketType> = SocketMessage<SocketPacketRequestData<TType>, TType>;
+/**
+ * typed success message.
+ */
+export declare type SocketResponseMessage<TType extends SocketPacketType = SocketPacketType> = SocketMessage<SocketPacketResponseData<TType>, SocketPacketOkType<TType>>;
+/**
+ * typed error message.
+ */
+export declare type SocketErrorMessage<TType extends SocketPacketType = SocketPacketType> = SocketMessage<SocketPacketErrorData<TType>, SocketPacketErrorType<TType>>;
+/**
+ * helper to infer request payload from packet type.
+ */
+export declare type InferSocketRequest<TType extends SocketPacketType> = SocketPacketRequestData<TType>;
+/**
+ * helper to infer success payload from packet type.
+ */
+export declare type InferSocketResponse<TType extends SocketPacketType> = SocketPacketResponseData<TType>;
+/**
+ * helper to infer error payload from packet type.
+ */
+export declare type InferSocketError<TType extends SocketPacketType> = SocketPacketErrorData<TType>;
+/**
+ * optional normalized error shape for higher-level usage.
+ * - transport still uses `SocketMessage.error` as the primary field.
+ */
+export interface SocketErrorShape {
+    message: string;
+    code?: string;
+    retryable?: boolean;
+}

package/dist/lib/types.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * `lib/types.ts`
+ * - shared socket packet contracts for both server and client.
+ *
+ * RULES
+ * - every new socket packet type must be registered here first.
+ * - `SocketMessage<T>` payload usage must be derived from this file.
+ * - server/client code should treat this file as the source of truth for packet shapes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@lemoncloud/chatic-sockets-lib",
+  "version": "0.1.0",
+  "description": "Client websocket transport and sync runtime for chatic sockets v2",
+  "main": "dist/client-socket-v2/index.js",
+  "types": "dist/client-socket-v2/index.d.ts",
+  "files": [
+    "dist/**/*",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/client-socket-v2/index.d.ts",
+      "require": "./dist/client-socket-v2/index.js",
+      "default": "./dist/client-socket-v2/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "websocket",
+    "aws-apigateway",
+    "lambda",
+    "sync",
+    "chatic"
+  ],
+  "license": "MIT",
+  "sideEffects": true,
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}