@rocketmq/core 0.1.2 → 0.1.3

package/dist/index.d.ts

@@ -1,11 +1,40 @@
-import { SchemaRegistry } from '@rocketmq/schema';
+import { Constructor, SchemaRegistry } from '@rocketmq/schema';
 export { Field, FieldMeta, ProtoType, Schema, SchemaEntry } from '@rocketmq/schema';
+import { ZodSchemaInput } from '@rocketmq/zod';
+export { ZodSchemaInput, isRawZodObject, isZodSchemaInput, zodToFields, zodToProto } from '@rocketmq/zod';
+import { z } from 'zod';
 import { Serializer } from '@rocketmq/serializer';
 export { Serializer } from '@rocketmq/serializer';
-import * as _rocketmq_amqp from '@rocketmq/amqp';
-import { AmqpChannel, PublishOptions, ConsumeMessage, ConsumeOptions, AmqpConnection, AssertQueueOptions, AssertQueueReply, AssertExchangeOptions, AssertExchangeReply, EmptyReply } from '@rocketmq/amqp';
+import { PublishOptions, ConsumeOptions, AmqpConnection, AmqpChannel, AssertQueueOptions, AssertQueueReply, AssertExchangeOptions, AssertExchangeReply, EmptyReply, ConsumeMessage } from '@rocketmq/amqp';
 export { ConsumeMessage } from '@rocketmq/amqp';
 
+/**
+ * Resolves proto3 definitions from decorator classes, Zod wrappers, or raw ZodObjects.
+ *
+ * Centralizes the tri-input logic so client.ts and queue-handle.ts stay
+ * clean — they just call `resolveProto(input, queueName)` without caring
+ * which path produced it.
+ *
+ * Usage:
+ *   resolveProto(NotificationClass, 'q');
+ *   resolveProto({ name: 'Notif', schema: zodSchema }, 'q');
+ *   resolveProto(zodSchema, 'q');  // message name derived from queue name
+ */
+
+/**
+ * Union type accepted by assertQueue/consume as the schema parameter.
+ *
+ * Three shapes:
+ *   - `Constructor<T>` — decorator class
+ *   - `ZodSchemaInput` — `{ name, schema }` wrapper with explicit message name
+ *   - `z.ZodType<T>` — bare Zod schema, message name derived from queue name
+ *
+ * WHY z.ZodType<T> instead of z.ZodObject: ZodObject<ZodRawShape> erases T,
+ * so TS can't infer the message type in consume(). ZodType<T> preserves
+ * the output type. Runtime still validates it's a ZodObject via isRawZodObject.
+ */
+type SchemaInput<T = unknown> = Constructor<T> | ZodSchemaInput | z.ZodType<T>;
+
 /**
  * Typed queue handle — the core DX innovation.
  *
@@ -21,10 +50,9 @@ export { ConsumeMessage } from '@rocketmq/amqp';
 
 declare class QueueHandle<T> {
     private readonly queueName;
-    private readonly channel;
-    private readonly registry;
-    private readonly serializer;
-    constructor(queueName: string, channel: AmqpChannel, registry: SchemaRegistry, serializer: Serializer);
+    private readonly client;
+    private readonly schema;
+    constructor(queueName: string, client: RocketMQ, schema: SchemaInput<T>);
     /**
      * Publishes a typed payload to this queue.
      *
@@ -38,24 +66,62 @@ declare class QueueHandle<T> {
      * arguments so the broker can verify schema subset compatibility.
      * Malformed messages are logged but not re-thrown to keep the loop alive.
      */
-    consume(handler: (msg: T, raw: ConsumeMessage) => void, opts?: ConsumeOptions): Promise<string>;
-    /** Builds AMQP arguments for consumer schema subset checking. */
-    private buildConsumerSchemaArgs;
+    consume(handler: TypedConsumeHandler<T>, opts?: ConsumeOptions): Promise<string>;
 }
 
+/**
+ * RocketMQ TypeScript client — schema-aware AMQP wrapper.
+ *
+ * Composes schema, validation, serialization, and AMQP packages into
+ * a single user-facing API. Hides all internal wiring behind `connect()`
+ * and `mq.queue()`.
+ *
+ * Supports two schema input styles:
+ *   - Decorator classes: `mq.assertQueue('q', MyClass)`
+ *   - Zod schemas:       `mq.assertQueue('q', { name: 'Msg', schema: zodObj })`
+ *
+ * Usage:
+ *   const mq = await connect();
+ *   const orders = mq.queue("orders", Order);
+ *   orders.send({ id: "1", customerId: "c1", qty: 5 });
+ */
+
+type TypedConsumeHandler<T> = (msg: T, raw: ConsumeMessage) => void | Promise<void>;
+interface RocketAssertQueueOptions extends AssertQueueOptions {
+    /** Force update an existing queue's schema even if it conflicts. */
+    schemaOverride?: boolean;
+    /** Remove the schema binding from an existing queue. */
+    schemaDelete?: boolean;
+}
+interface RocketConsumeOptions extends ConsumeOptions {
+    /**
+     * Explicit schema class for consumer compatibility validation.
+     *
+     * TypeScript generics are erased at runtime, so `consume<T>` alone
+     * cannot send `T`'s proto to the broker. Pass the class here so the
+     * broker can verify the consumer's expected fields match the queue's
+     * declared schema.
+     *
+     * Example:
+     *   await mq.consume<Order>('orders', handler, { consumerSchema: Order });
+     */
+    consumerSchema?: Constructor;
+}
 interface RocketOptions {
-    /** AMQP connection URL. Default: amqp://guest:guest@localhost:5672 */
-    url?: string;
+    /** AMQP connection URL. */
+    url: string;
     /** Custom serializer. Default: JsonSerializer. */
     serializer?: Serializer;
 }
 /** Opens a connection + channel ready for schema-aware operations. */
-declare function connect(opts?: RocketOptions): Promise<RocketMQ>;
+declare function connect(opts: RocketOptions): Promise<RocketMQ>;
 declare class RocketMQ {
     private readonly conn;
     private readonly ch;
     private readonly registry;
     private readonly serializer;
+    private lastChannelError;
+    private readonly errorListener;
     constructor(conn: AmqpConnection, ch: AmqpChannel, registry: SchemaRegistry, serializer: Serializer);
     /** Exposes the raw AmqpChannel for event listeners (e.g. broker errors). */
     get channel(): AmqpChannel;
@@ -65,16 +131,28 @@ declare class RocketMQ {
      * Declares the queue with schema metadata in AMQP arguments so the
      * broker compiles and validates messages. Returns a QueueHandle<T>
      * for type-safe send/consume.
+     *
+     * Usage:
+     *   const orders = await mq.queue('orders', OrderClass);
+     *   const orders = await mq.queue('orders', zodSchema);
      */
-    queue<T>(name: string, schema: new (...args: unknown[]) => T, opts?: AssertQueueOptions): Promise<QueueHandle<T>>;
+    queue<T>(name: string, schema: SchemaInput<T>, opts?: RocketAssertQueueOptions): Promise<QueueHandle<T>>;
     /**
-     * Declares a queue with an optional schema class.
+     * Declares a queue with an optional schema (decorator class or Zod).
      *
      * When a schema is provided the proto3 definition is sent as AMQP
      * queue arguments (`x-schema`, `x-schema-type`, `x-schema-message`)
      * so the broker compiles and validates messages inline.
+     *
+     * Usage:
+     *   await mq.assertQueue('orders', OrderClass);
+     *   await mq.assertQueue('orders', { name: 'Order', schema: zodSchema });
+     *   await mq.assertQueue('orders', zodSchema);  // message name derived from queue name
      */
-    assertQueue(name: string, schema?: Function, opts?: AssertQueueOptions): Promise<AssertQueueReply>;
+    assertQueue(name: string, schema?: SchemaInput, opts?: RocketAssertQueueOptions): Promise<AssertQueueReply>;
+    private buildSchemaQueueArgs;
+    /** Stores decorator class metadata in the registry for consumer lookups. */
+    private registerConstructorSchema;
     /** Declares an exchange (passthrough to AMQP layer). */
     assertExchange(name: string, type: string, opts?: AssertExchangeOptions): Promise<AssertExchangeReply>;
     /** Binds a queue to an exchange (passthrough to AMQP layer). */
@@ -91,25 +169,27 @@ declare class RocketMQ {
      */
     publish(exchange: string, routingKey: string, payload: Record<string, unknown>, opts?: PublishOptions): boolean;
     /**
-     * Subscribes to a queue with JSON deserialization.
+     * Subscribes to a queue with JSON deserialization and broker-side
+     * consumer schema validation.
      *
-     * When a schema was registered via `assertQueue(name, Schema)`,
-     * the consumer's proto definition is sent to the broker for subset
-     * checking — the broker rejects consumers expecting fields the
-     * queue's schema doesn't define.
+     * Accepts either a decorator class or a ZodSchemaInput for the schema
+     * parameter. The schema serves two purposes:
+     * - **Compile-time**: TypeScript infers `T`, so `msg` is fully typed.
+     * - **Runtime**: Its proto definition is sent to the broker as AMQP
+     *   arguments so the broker can verify subset compatibility.
      *
      * Usage:
-     *   await mq.assertQueue("orders", Order);
-     *   await mq.consume("orders", (msg) => console.log(msg));
-     */
-    consume<T = Record<string, unknown>>(queue: string, handler: (msg: T, raw: ConsumeMessage) => void, opts?: _rocketmq_amqp.ConsumeOptions): Promise<string>;
-    /**
-     * Builds AMQP arguments for consumer schema compatibility checking.
-     *
-     * Returns `x-consumer-schema` + `x-consumer-schema-message` if the
-     * queue has a registered schema, otherwise an empty object.
+     *   await mq.consume("orders", Order, (msg) => console.log(msg.id));
+     *   await mq.consume("orders", { name: "Order", schema: zodSchema }, handler);
+     *   await mq.consume("orders", zodSchema, handler);
      */
+    consume<T>(queue: string, schema: SchemaInput<T>, handler: TypedConsumeHandler<T>, opts?: RocketConsumeOptions): Promise<string>;
+    private createConsumeCallback;
     private buildConsumerSchemaArgs;
+    /** Resolves consumer schema args from an explicit SchemaInput. */
+    private resolveConsumerArgs;
+    /** Falls back to registry lookup when no explicit schema is provided. */
+    private fallbackConsumerArgs;
     /** Acknowledges a message. */
     ack(msg: ConsumeMessage): void;
     /** Negative-acknowledges a message. */
@@ -142,19 +222,161 @@ declare class QueueError extends RocketMQError {
 }
 declare class PublishError extends RocketMQError {
     readonly queue: string;
-    constructor(queue: string, cause?: unknown);
+    readonly payload: unknown;
+    constructor(queue: string, payload: unknown, cause?: unknown);
 }
 declare class ConsumeError extends RocketMQError {
     constructor(message: string, cause?: unknown);
 }
 declare class SerializationError extends RocketMQError {
-    constructor(message: string, cause?: unknown);
+    readonly payload: unknown;
+    constructor(payload: unknown, cause?: unknown);
 }
 declare class SchemaError extends RocketMQError {
     constructor(message: string, cause?: unknown);
 }
+/**
+ * Schema-specific error with structured details from the broker.
+ *
+ * Contains the error code, queue name, and per-field details
+ * so callers can programmatically inspect what went wrong.
+ * Field types use TypeScript names (number, string, boolean).
+ *
+ * Usage:
+ *   catch (err) {
+ *     if (err instanceof SchemaValidationError) {
+ *       console.log(err.code);     // 'SchemaTypeMismatch'
+ *       console.log(err.queue);    // 'zod-notifications'
+ *       console.log(err.fields);   // [{ name: 'id', expected: 'number', got: 'string' }]
+ *     }
+ *   }
+ */
+declare class SchemaValidationError extends SchemaError {
+    readonly code: string;
+    readonly queue: string;
+    readonly fields: ReadonlyArray<{
+        readonly name: string;
+        readonly expected: string;
+        readonly got: string;
+    }>;
+    constructor(code: string, queue: string, fields: ReadonlyArray<{
+        readonly name: string;
+        readonly expected: string;
+        readonly got: string;
+    }>, message: string, cause?: unknown);
+}
 declare class TimeoutError extends RocketMQError {
     constructor(message: string, cause?: unknown);
 }
 
-export { ConnectionError, ConsumeError, PublishError, QueueError, QueueHandle, RocketMQ, RocketMQError, type RocketOptions, SchemaError, SerializationError, TimeoutError, connect };
+/**
+ * Machine-readable error codes returned by the broker.
+ *
+ * These mirror the Rust `ErrorCode` enum 1:1. The client uses them
+ * to construct specific exception subclasses and provide programmatic
+ * access to the error category.
+ *
+ * Usage:
+ *   if (parsed.code === BrokerErrorCode.SchemaTypeMismatch) { ... }
+ */
+declare enum BrokerErrorCode {
+    /** Consumer/publisher field type doesn't match queue schema. */
+    SchemaTypeMismatch = "SchemaTypeMismatch",
+    /** Consumer has fields not present in queue schema. */
+    SchemaExtraFields = "SchemaExtraFields",
+    /** JSON payload is missing required schema fields. */
+    SchemaMissingFields = "SchemaMissingFields",
+    /** Re-declaration schema conflicts with existing queue schema. */
+    SchemaConflict = "SchemaConflict",
+    /** Proto compilation failed (syntax error, etc.). */
+    SchemaCompileFailed = "SchemaCompileFailed",
+    /** Unsupported schema type (not protobuf). */
+    SchemaUnsupportedType = "SchemaUnsupportedType",
+    /** Schema validation on publish: wrong JSON value types. */
+    ValidationTypeMismatch = "ValidationTypeMismatch",
+    /** Payload is not valid JSON. */
+    ValidationInvalidJson = "ValidationInvalidJson",
+    /** Required AMQP argument missing (x-schema-type, x-schema-message). */
+    MissingArgument = "MissingArgument"
+}
+
+/**
+ * Parses structured JSON errors from AMQP Channel.Close reply_text.
+ *
+ * The broker encodes a `BrokerError` JSON object into the reply_text
+ * field. This module detects JSON (starts with `{`), validates the shape,
+ * and returns a typed `BrokerErrorPayload`.
+ *
+ * It also handles proto → TypeScript type name mapping, since the broker
+ * returns raw proto names (e.g. "double") and the client translates them
+ * to language-specific names (e.g. "number").
+ *
+ * Usage:
+ *   const parsed = parseBrokerError(replyText);
+ *   if (parsed) throw SchemaValidationError.fromBrokerError(parsed);
+ */
+
+/** Structured error payload deserialized from broker JSON. */
+interface BrokerErrorPayload {
+    code: BrokerErrorCode;
+    queue: string;
+    fields: FieldErrorDetail[];
+    truncated: boolean;
+}
+/** Per-field error detail from the broker. */
+interface FieldErrorDetail {
+    /** Field name in the schema. */
+    name: string;
+    /** Proto type name that the queue schema expects (e.g. "double"). */
+    expected: string;
+    /** Proto type name that was actually received (e.g. "string"). */
+    got: string;
+}
+/**
+ * Maps proto3 type names to TypeScript-friendly equivalents.
+ *
+ * WHY here and not in the broker: the broker is language-agnostic.
+ * It returns raw proto kind names. Each client SDK maps them to the
+ * target language's type system.
+ *
+ * Usage:
+ *   protoToTsType('double') // => 'number'
+ *   protoToTsType('int32')  // => 'number'
+ *   protoToTsType('bool')   // => 'boolean'
+ */
+declare function protoToTsType(protoType: string): string;
+/**
+ * Attempts to parse a structured broker error from AMQP reply_text.
+ *
+ * Returns `null` if the reply_text is a plain string (not JSON)
+ * or doesn't match the expected `BrokerErrorPayload` shape.
+ *
+ * Usage:
+ *   const payload = parseBrokerError('{"code":"SchemaTypeMismatch",...}');
+ */
+declare function parseBrokerError(replyText: string): BrokerErrorPayload | null;
+/**
+ * Extracts the reply_text from an amqplib channel error message.
+ *
+ * amqplib formats errors as:
+ *   'Channel closed by server: 406 (PRECONDITION-FAILED) with message "..."'
+ *
+ * We extract the content between the last pair of double quotes.
+ *
+ * Usage:
+ *   extractReplyText(new Error('...with message "{\"code\":...}"'))
+ */
+declare function extractReplyText(err: unknown): string | null;
+/**
+ * Formats a `BrokerErrorPayload` into a developer-friendly message.
+ *
+ * Uses TypeScript type names (via `protoToTsType`) so the error
+ * reads naturally to TS developers.
+ *
+ * Usage:
+ *   formatBrokerError(payload)
+ *   // => "Queue 'orders': field 'id' is number in queue but got string"
+ */
+declare function formatBrokerError(payload: BrokerErrorPayload): string;
+
+export { BrokerErrorCode, type BrokerErrorPayload, ConnectionError, ConsumeError, type FieldErrorDetail, PublishError, QueueError, QueueHandle, type RocketAssertQueueOptions, type RocketConsumeOptions, RocketMQ, RocketMQError, type RocketOptions, SchemaError, type SchemaInput, SchemaValidationError, SerializationError, TimeoutError, connect, extractReplyText, formatBrokerError, parseBrokerError, protoToTsType };