@dotdo/do 0.1.0

package/dist/rpc/protocol.d.ts

@@ -0,0 +1,310 @@
+/**
+ * CapnWeb RPC Protocol
+ *
+ * Message serialization, validation, and parsing for the RPC transport.
+ * Implements JSON-RPC style messages without requiring schema compilation.
+ *
+ * @module rpc/protocol
+ *
+ * @example
+ * ```typescript
+ * import { parseRequest, serializeResponse, validateRequest } from 'do/rpc/protocol'
+ *
+ * // Parse incoming message
+ * const request = parseRequest(rawMessage)
+ *
+ * // Validate request structure
+ * const validation = validateRequest(request)
+ * if (!validation.valid) {
+ *   return serializeResponse({
+ *     id: request?.id ?? 'unknown',
+ *     error: { code: -32600, message: validation.error }
+ *   })
+ * }
+ *
+ * // Serialize response
+ * const response = serializeResponse({
+ *   id: request.id,
+ *   result: { data: 'value' }
+ * })
+ * ```
+ */
+import type { RPCRequest, RPCResponse, RPCError, RPCMeta, RPCBatchRequest, RPCBatchResponse } from '../types/rpc';
+/**
+ * RPC Protocol Error
+ *
+ * Thrown when there's an error parsing or validating RPC messages.
+ */
+export declare class RPCProtocolError extends Error {
+    constructor(message: string);
+}
+/**
+ * RPC Error type names for createRPCError
+ */
+export type RPCErrorType = 'ParseError' | 'InvalidRequest' | 'MethodNotFound' | 'InvalidParams' | 'InternalError' | 'Unauthorized' | 'Forbidden' | 'NotFound' | 'Conflict' | 'RateLimited' | 'Timeout';
+/**
+ * Result of parsing a raw message
+ */
+export interface ParseResult<T> {
+    /** Whether parsing succeeded */
+    success: boolean;
+    /** Parsed data on success */
+    data?: T;
+    /** Error message on failure */
+    error?: string;
+}
+/**
+ * Result of validating a request
+ */
+export interface ValidationResult {
+    /** Whether validation passed */
+    valid: boolean;
+    /** Error message on failure */
+    error?: string;
+    /** Specific field that failed validation */
+    field?: string;
+}
+/**
+ * Options for serialization
+ */
+export interface SerializeOptions {
+    /** Pretty print JSON (default: false) */
+    pretty?: boolean;
+    /** Include null values (default: false) */
+    includeNulls?: boolean;
+}
+/**
+ * Parse a raw message into an RPC request
+ *
+ * Handles both single requests and batch requests.
+ * Returns a ParseResult with either the parsed request or an error message.
+ *
+ * @param message - Raw message string (expected to be JSON)
+ * @returns ParseResult containing either the parsed request or error
+ *
+ * @example
+ * ```typescript
+ * const result = parseRequest('{"id":"1","method":"do.things.list"}')
+ * if (result.success) {
+ *   console.log(result.data.method) // 'do.things.list'
+ * }
+ * ```
+ */
+export declare function parseRequest(message: string | ArrayBuffer): ParseResult<RPCRequest | RPCBatchRequest>;
+/**
+ * Parse a raw message into an RPC response
+ *
+ * @param message - Raw message string (expected to be JSON)
+ * @returns ParseResult containing either the parsed response or error
+ */
+export declare function parseResponse(message: string | ArrayBuffer): ParseResult<RPCResponse | RPCBatchResponse>;
+/**
+ * Deserialize a raw message into an RPC request
+ *
+ * @param message - Raw message string (expected to be JSON)
+ * @returns Parsed RPC request
+ * @throws RPCProtocolError if parsing or validation fails
+ */
+export declare function deserializeRequest(message: string): RPCRequest;
+/**
+ * Deserialize a raw message into an RPC response
+ *
+ * @param message - Raw message string (expected to be JSON)
+ * @returns Parsed RPC response
+ * @throws RPCProtocolError if parsing or validation fails
+ */
+export declare function deserializeResponse(message: string): RPCResponse;
+/**
+ * Deserialize a raw message into an RPC batch request
+ *
+ * @param message - Raw message string (expected to be JSON)
+ * @returns Parsed RPC batch request
+ * @throws RPCProtocolError if parsing or validation fails
+ */
+export declare function deserializeBatchRequest(message: string): RPCBatchRequest;
+/**
+ * Deserialize a raw message into an RPC batch response
+ *
+ * @param message - Raw message string (expected to be JSON)
+ * @returns Parsed RPC batch response
+ * @throws RPCProtocolError if parsing or validation fails
+ */
+export declare function deserializeBatchResponse(message: string): RPCBatchResponse;
+/**
+ * Validate an RPC request structure
+ *
+ * Checks that the request has:
+ * - A string `id` field
+ * - A string `method` field in correct format (e.g., 'do.namespace.action')
+ * - Optional `params` object
+ * - Optional `meta` object with valid fields
+ *
+ * @param request - The request to validate
+ * @returns ValidationResult indicating success or failure with details
+ *
+ * @example
+ * ```typescript
+ * const validation = validateRequest({ id: '1', method: 'invalid' })
+ * if (!validation.valid) {
+ *   console.log(validation.error) // 'Invalid method format'
+ * }
+ * ```
+ */
+export declare function validateRequest(request: unknown): void;
+/**
+ * Validate an RPC response structure
+ *
+ * @param response - The response to validate
+ * @throws RPCProtocolError if validation fails
+ */
+export declare function validateResponse(response: unknown): void;
+/**
+ * Validate a batch request structure
+ *
+ * @param batch - The batch request to validate
+ * @throws RPCProtocolError if validation fails
+ */
+export declare function validateBatchRequest(batch: unknown): void;
+/**
+ * Validate method name format
+ *
+ * Method names must follow the pattern: `do.{namespace}.{action}`
+ * Examples: 'do.things.list', 'do.identity.get', 'do.cdc.subscribe'
+ *
+ * @param method - The method name to validate
+ * @returns Whether the method name is valid
+ */
+export declare function validateMethodName(method: string): boolean;
+/**
+ * Serialize an RPC request to a string
+ *
+ * @param request - The request to serialize
+ * @param options - Serialization options
+ * @returns JSON string representation
+ *
+ * @example
+ * ```typescript
+ * const json = serializeRequest({
+ *   id: '1',
+ *   method: 'do.things.list',
+ *   params: { limit: 10 }
+ * })
+ * // '{"id":"1","method":"do.things.list","params":{"limit":10}}'
+ * ```
+ */
+export declare function serializeRequest(request: RPCRequest, options?: SerializeOptions): string;
+/**
+ * Serialize an RPC response to a string
+ *
+ * @param response - The response to serialize
+ * @param options - Serialization options
+ * @returns JSON string representation
+ */
+export declare function serializeResponse(response: RPCResponse, options?: SerializeOptions): string;
+/**
+ * Serialize a batch request to a string
+ *
+ * @param batch - The batch request to serialize
+ * @param options - Serialization options
+ * @returns JSON string representation
+ */
+export declare function serializeBatchRequest(batch: RPCBatchRequest, options?: SerializeOptions): string;
+/**
+ * Serialize a batch response to a string
+ *
+ * @param batch - The batch response to serialize
+ * @param options - Serialization options
+ * @returns JSON string representation
+ */
+export declare function serializeBatchResponse(batch: RPCBatchResponse, options?: SerializeOptions): string;
+/**
+ * Create an RPC error object
+ *
+ * @param code - Error code (from RpcErrorCodes)
+ * @param message - Human-readable error message
+ * @param data - Optional additional error data
+ * @returns RPCError object
+ *
+ * @example
+ * ```typescript
+ * const error = createError(-32601, 'Method not found', { method: 'do.invalid' })
+ * ```
+ */
+export declare function createError(code: number, message: string, data?: unknown): RPCError;
+/**
+ * Create an RPC error object by type name
+ *
+ * @param type - Error type name
+ * @param message - Human-readable error message
+ * @param data - Optional additional error data
+ * @returns RPCError object
+ *
+ * @example
+ * ```typescript
+ * const error = createRPCError('MethodNotFound', 'Unknown method: do.invalid')
+ * ```
+ */
+export declare function createRPCError(type: RPCErrorType, message: string, data?: unknown): RPCError;
+/**
+ * Check if a value is an RPC error
+ *
+ * @param value - Value to check
+ * @returns Whether the value is a valid RPC error
+ */
+export declare function isRPCError(value: unknown): value is RPCError;
+/**
+ * Create an error response for a request
+ *
+ * @param requestId - The ID of the request that failed
+ * @param code - Error code
+ * @param message - Error message
+ * @param data - Optional error data
+ * @returns Complete RPCResponse with error
+ */
+export declare function createErrorResponse(requestId: string, code: number, message: string, data?: unknown): RPCResponse;
+/**
+ * Create a success response for a request
+ *
+ * @param requestId - The ID of the request
+ * @param result - The result data
+ * @param meta - Optional metadata
+ * @returns Complete RPCResponse with result
+ */
+export declare function createSuccessResponse<T>(requestId: string, result: T, meta?: RPCMeta): RPCResponse<T>;
+/**
+ * Generate a unique request ID
+ *
+ * Uses a combination of timestamp and random string for uniqueness.
+ *
+ * @returns Unique request ID string
+ */
+export declare function generateRequestId(): string;
+/**
+ * Check if a message is a batch request
+ *
+ * @param message - Parsed message object
+ * @returns Whether the message is a batch request
+ */
+export declare function isBatchRequest(message: unknown): message is RPCBatchRequest;
+/**
+ * Check if a message is a batch response
+ *
+ * @param message - Parsed message object
+ * @returns Whether the message is a batch response
+ */
+export declare function isBatchResponse(message: unknown): message is RPCBatchResponse;
+/**
+ * Extract namespace from method name
+ *
+ * @param method - Method name (e.g., 'do.things.list')
+ * @returns Namespace (e.g., 'things')
+ */
+export declare function extractNamespace(method: string): string | null;
+/**
+ * Extract action from method name
+ *
+ * @param method - Method name (e.g., 'do.things.list')
+ * @returns Action (e.g., 'list')
+ */
+export declare function extractAction(method: string): string | null;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/rpc/protocol.d.ts.map

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