@jaypie/fabric 0.2.0 → 0.2.2

package/dist/cjs/websocket/fabricWebSocket.d.ts

@@ -0,0 +1,120 @@
+import type { BroadcastResult, SendResult, WebSocketContext, WebSocketEvent, WebSocketResponse } from "@jaypie/lambda";
+import type { InputFieldDefinition, Message, Service, ServiceContext, ServiceFunction } from "../types.js";
+/** Callback called when handler completes successfully */
+export type OnCompleteCallback = (response: unknown) => void | Promise<void>;
+/** Callback called for recoverable errors (via context.onError) */
+export type OnErrorCallback = (error: unknown) => void | Promise<void>;
+/** Callback called for fatal errors (thrown or via context.onFatal) */
+export type OnFatalCallback = (error: unknown) => void | Promise<void>;
+/** Callback for receiving messages from service during execution */
+export type OnMessageCallback = (message: Message) => void | Promise<void>;
+/** Callback for $connect event */
+export type OnConnectCallback = (context: WebSocketContext) => void | Promise<void>;
+/** Callback for $disconnect event */
+export type OnDisconnectCallback = (context: WebSocketContext) => void | Promise<void>;
+type LifecycleFunction = (...args: unknown[]) => void | Promise<void>;
+type ValidatorFunction = (...args: unknown[]) => unknown | Promise<unknown>;
+/**
+ * Extended service context for WebSocket handlers
+ */
+export interface WebSocketServiceContext extends ServiceContext {
+    /** Broadcast data to multiple connections */
+    broadcast: (connectionIds: string[], data: unknown) => Promise<BroadcastResult>;
+    /** The WebSocket connection ID */
+    connectionId: string;
+    /** The WebSocket API domain name */
+    domainName: string;
+    /** Query string parameters from $connect */
+    queryStringParameters: Record<string, string> | null;
+    /** The route key (e.g., "$connect", "$disconnect", "$default", or custom) */
+    routeKey: string;
+    /** Send data to the current connection */
+    send: (data: unknown) => Promise<SendResult>;
+    /** The WebSocket API stage */
+    stage: string;
+}
+/**
+ * Options for fabricWebSocket
+ */
+export interface FabricWebSocketOptions {
+    /** Chaos testing mode */
+    chaos?: string;
+    /** Override the service name for logging (defaults to service.alias) */
+    name?: string;
+    /** Callback for $connect events */
+    onConnect?: OnConnectCallback;
+    /** Callback called when handler completes successfully */
+    onComplete?: OnCompleteCallback;
+    /** Callback for $disconnect events */
+    onDisconnect?: OnDisconnectCallback;
+    /** Callback for recoverable errors (via context.onError) */
+    onError?: OnErrorCallback;
+    /** Callback for fatal errors (thrown or via context.onFatal) */
+    onFatal?: OnFatalCallback;
+    /** Callback for receiving messages from service during execution */
+    onMessage?: OnMessageCallback;
+    /** AWS secrets to load into process.env */
+    secrets?: string[];
+    /** Functions to run before handler */
+    setup?: LifecycleFunction[];
+    /** Functions to run after handler (always runs) */
+    teardown?: LifecycleFunction[];
+    /** Re-throw errors instead of returning error response */
+    throw?: boolean;
+    /** Return 503 Unavailable immediately */
+    unavailable?: boolean;
+    /** Validation functions to run before handler */
+    validate?: ValidatorFunction[];
+}
+/**
+ * Configuration for fabricWebSocket
+ */
+export interface FabricWebSocketConfig extends FabricWebSocketOptions {
+    /** Service alias (used as name for logging if `name` not provided) */
+    alias?: string;
+    /** Service description */
+    description?: string;
+    /** Input field definitions */
+    input?: Record<string, InputFieldDefinition>;
+    /** The service - either a pre-instantiated Service or an inline function */
+    service: Service | ServiceFunction<Record<string, unknown>, unknown>;
+}
+/**
+ * The returned WebSocket Lambda handler function
+ */
+export type FabricWebSocketResult = (event: WebSocketEvent, context?: {
+    awsRequestId?: string;
+    [key: string]: unknown;
+}, ...args: unknown[]) => Promise<WebSocketResponse>;
+/**
+ * Fabric a WebSocket Lambda handler that wraps a service.
+ *
+ * This function creates a WebSocket-compatible Lambda handler that:
+ * - Parses the WebSocket body as service input
+ * - Provides WebSocket context (connectionId, send, broadcast) to the service
+ * - Handles $connect and $disconnect events with optional callbacks
+ * - Integrates with websocketHandler for lifecycle management
+ *
+ * @example
+ * ```typescript
+ * import { fabricWebSocket } from "@jaypie/fabric/websocket";
+ * import { myService } from "./services";
+ *
+ * // Direct service style
+ * export const handler = fabricWebSocket(myService);
+ *
+ * // Config object style with lifecycle hooks
+ * export const handler2 = fabricWebSocket({
+ *   service: myService,
+ *   secrets: ["MONGODB_URI"],
+ *   onConnect: async (context) => {
+ *     await storeConnection(context.connectionId);
+ *   },
+ *   onDisconnect: async (context) => {
+ *     await removeConnection(context.connectionId);
+ *   },
+ * });
+ * ```
+ */
+export declare function fabricWebSocket(serviceOrConfig: FabricWebSocketConfig | Service | ServiceFunction<Record<string, unknown>, unknown>, options?: FabricWebSocketOptions): FabricWebSocketResult;
+export {};

package/dist/cjs/websocket/index.d.ts

@@ -0,0 +1,2 @@
+export { fabricWebSocket } from "./fabricWebSocket.js";
+export type { FabricWebSocketConfig, FabricWebSocketOptions, FabricWebSocketResult, OnCompleteCallback, OnConnectCallback, OnDisconnectCallback, OnErrorCallback, OnFatalCallback, OnMessageCallback, WebSocketServiceContext, } from "./fabricWebSocket.js";

package/dist/esm/ServiceSuite.d.ts

@@ -43,7 +43,9 @@ export interface ServiceSuite {
     /** Execute a service by name */
     execute(name: string, inputs: Record<string, unknown>): Promise<unknown>;
     /** Register a fabricService into the suite */
-    register(service: Service<any, any>, category: string): void;
+    register(service: Service<any, any>, options: {
+        category: string;
+    }): void;
     /** Get all registered service functions (for transport adapters like FabricMcpServer) */
     getServiceFunctions(): Service<any, any>[];
     /** Get a specific service function by name */

package/dist/esm/commander/index.js

@@ -856,42 +856,68 @@ async function processField(fieldName, value, definition) {
 function isService(value) {
     return typeof value === "function" && "$fabric" in value;
 }
+/**
+ * Run serializer hook if provided
+ * Returns transformed output or original if serializer returns undefined/null/void
+ */
+async function runSerializer(data, serializer, context) {
+    if (!serializer) {
+        return data.output;
+    }
+    const result = await serializer(data, context);
+    if (result !== undefined && result !== null) {
+        return result;
+    }
+    return data.output;
+}
 /**
  * Fabric a service function
  *
- * Service builds a function that initiates a "controller" step that:
+ * Service builds a function that:
  * - Parses the input if it is a string to object
  * - Fabrics each input field to its type
  * - Calls the validation function or regular expression or checks the array
- * - Calls the service function and returns the response
+ * - Calls the service function
+ * - Calls the serializer hook (can transform output)
+ * - Returns the response
  *
  * The returned function has config properties for introspection.
  */
 function fabricService(config) {
-    const { input: inputDefinitions, service } = config;
+    const { input: inputDefinitions, serializer, service } = config;
     const handler = async (rawInput, context) => {
         // Parse input (handles string JSON)
         const parsedInput = parseInput(rawInput);
         // If no input definitions, pass through to service or return parsed input
         if (!inputDefinitions) {
+            let output;
             if (service) {
-                return service(parsedInput, context);
+                output = await service(parsedInput, context);
             }
-            return parsedInput;
+            else {
+                output = parsedInput;
+            }
+            // Run serializer
+            return (await runSerializer({ input: parsedInput, output }, serializer, context));
         }
         // Process all fields in parallel
         const entries = Object.entries(inputDefinitions);
         const processedValues = await Promise.all(entries.map(([fieldName, definition]) => processField(fieldName, parsedInput[fieldName], definition)));
         // Build processed input object
-        const processedInput = {};
+        const processedInputObj = {};
         entries.forEach(([fieldName], index) => {
-            processedInput[fieldName] = processedValues[index];
+            processedInputObj[fieldName] = processedValues[index];
         });
-        // Return processed input if no service, otherwise call service
+        // Call service or return processed input
+        let output;
         if (service) {
-            return service(processedInput, context);
+            output = await service(processedInputObj, context);
+        }
+        else {
+            output = processedInputObj;
         }
-        return processedInput;
+        // Run serializer hook
+        return (await runSerializer({ input: processedInputObj, output }, serializer, context));
     };
     // Attach config properties directly to handler for flat access
     const typedHandler = handler;
@@ -902,6 +928,8 @@ function fabricService(config) {
         typedHandler.description = config.description;
     if (config.input !== undefined)
         typedHandler.input = config.input;
+    if (config.serializer !== undefined)
+        typedHandler.serializer = config.serializer;
     if (config.service !== undefined)
         typedHandler.service = config.service;
     return typedHandler;
@@ -920,6 +948,7 @@ function fabricService(config) {
  * - `alias` overrides service.alias
  * - `description` overrides service.description
  * - `input` overrides service.input
+ * - `serializer` overrides service.serializer
  *
  * The original Service is never mutated - a new Service is created when overrides
  * are applied.
@@ -943,7 +972,7 @@ function fabricService(config) {
  * ```
  */
 function resolveService(config) {
-    const { alias, description, input, service } = config;
+    const { alias, description, input, serializer, service } = config;
     if (isService(service)) {
         // Service is pre-instantiated - config fields act as overrides
         // Create new Service with merged properties (config overrides service)
@@ -951,6 +980,7 @@ function resolveService(config) {
             alias: alias ?? service.alias,
             description: description ?? service.description,
             input: input ?? service.input,
+            serializer: serializer ?? service.serializer,
             service: service.service,
         });
     }
@@ -959,6 +989,7 @@ function resolveService(config) {
         alias,
         description,
         input,
+        serializer,
         service,
     });
 }