@rocketmq/core 0.1.1 → 0.1.3

package/src/error-parser.ts

@@ -0,0 +1,189 @@
+/**
+ * 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);
+ */
+
+import { BrokerErrorCode } from './error-codes.js';
+import { SchemaValidationError } from './errors.js';
+
+/** Structured error payload deserialized from broker JSON. */
+export interface BrokerErrorPayload {
+  code: BrokerErrorCode;
+  queue: string;
+  fields: FieldErrorDetail[];
+  truncated: boolean;
+}
+
+/** Per-field error detail from the broker. */
+export 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'
+ */
+export function protoToTsType(protoType: string): string {
+  const mapping: Record<string, string> = {
+    double: 'number',
+    float: 'number',
+    int32: 'number',
+    int64: 'number',
+    uint32: 'number',
+    uint64: 'number',
+    sint32: 'number',
+    sint64: 'number',
+    fixed32: 'number',
+    fixed64: 'number',
+    sfixed32: 'number',
+    sfixed64: 'number',
+    bool: 'boolean',
+    string: 'string',
+    bytes: 'Uint8Array',
+    enum: 'enum',
+    message: 'object',
+  };
+  return mapping[protoType] ?? protoType;
+}
+
+/**
+ * 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",...}');
+ */
+export function parseBrokerError(replyText: string): BrokerErrorPayload | null {
+  if (!replyText.startsWith('{')) {
+    return null;
+  }
+
+  try {
+    const raw: unknown = JSON.parse(replyText);
+    if (typeof raw !== 'object' || raw === null) {
+      return null;
+    }
+
+    const obj = raw as Record<string, unknown>;
+    if (typeof obj['code'] !== 'string' || typeof obj['queue'] !== 'string') {
+      return null;
+    }
+
+    return {
+      code: obj['code'] as BrokerErrorCode,
+      queue: obj['queue'] as string,
+      fields: Array.isArray(obj['fields']) ? (obj['fields'] as FieldErrorDetail[]) : [],
+      truncated: obj['truncated'] === true,
+    };
+  } catch {
+    return 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\":...}"'))
+ */
+export function extractReplyText(err: unknown): string | null {
+  if (!(err instanceof Error)) {
+    return null;
+  }
+
+  const match = err.message.match(/with message "(.+)"$/);
+  return match?.[1] ?? 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"
+ */
+export function formatBrokerError(payload: BrokerErrorPayload): string {
+  const header = `[${payload.code}] Queue '${payload.queue}'`;
+
+  if (payload.fields.length === 0) {
+    return header;
+  }
+
+  const details = payload.fields
+    .map((f) => `  • ${f.name}: expected ${protoToTsType(f.expected)}, got ${protoToTsType(f.got)}`)
+    .join('\n');
+
+  const suffix = payload.truncated ? '\n  (some fields omitted)' : '';
+
+  return `${header}:\n${details}${suffix}`;
+}
+
+/**
+ * Extracts, parses, and converts an AMQP error into a typed SchemaValidationError.
+ * Returns null if the error is not a structured broker schema error.
+ */
+export function wrapBrokerError(err: unknown): SchemaValidationError | null {
+  const replyText = extractReplyText(err);
+  if (!replyText) {
+    return null;
+  }
+
+  const parsed = parseBrokerError(replyText);
+  if (!parsed) {
+    return null;
+  }
+
+  const tsFields = parsed.fields.map((f) => ({
+    name: f.name,
+    expected: protoToTsType(f.expected),
+    got: protoToTsType(f.got),
+  }));
+
+  return new SchemaValidationError(parsed.code, parsed.queue, tsFields, formatBrokerError(parsed));
+}
+
+/**
+ * Throws a typed SchemaValidationError if the error is a broker schema error,
+ * otherwise throws the provided fallback error.
+ */
+export function rethrowBrokerOr(err: unknown, fallback: Error): never {
+  const validationErr = wrapBrokerError(err);
+  if (validationErr) {
+    throw validationErr;
+  }
+  throw fallback;
+}

package/src/errors.test.ts

@@ -61,44 +61,47 @@ describe('QueueError', () => {
 });
 
 describe('PublishError', () => {
-  it('formats message with queue name', () => {
-    const err = new PublishError('orders');
-    expect(err.message).toBe("Failed to publish to 'orders'");
+  it('formats message with queue name and payload', () => {
+    const err = new PublishError('orders', { id: 1 });
+    expect(err.message).toBe('Failed to publish payload to \'orders\': {"id":1}');
     expect(err.queue).toBe('orders');
     expect(err.name).toBe('PublishError');
+    expect(err.payload).toEqual({ id: 1 });
   });
 
   it('preserves cause', () => {
     const cause = new Error('channel closed');
-    const err = new PublishError('q', cause);
+    const err = new PublishError('q', { id: 1 }, cause);
     expect(err.cause).toBe(cause);
   });
 });
 
 describe('ConsumeError', () => {
   it('extends RocketMQError', () => {
-    const err = new ConsumeError('consume fail');
+    const err = new ConsumeError('consume failed');
     expect(err).toBeInstanceOf(RocketMQError);
     expect(err.name).toBe('ConsumeError');
   });
 
   it('preserves cause', () => {
-    const cause = new Error('NOT_FOUND');
-    const err = new ConsumeError('failed', cause);
+    const cause = new Error('timeout');
+    const err = new ConsumeError('consume failed', cause);
     expect(err.cause).toBe(cause);
   });
 });
 
 describe('SerializationError', () => {
-  it('extends RocketMQError', () => {
-    const err = new SerializationError('bad json');
+  it('extends RocketMQError and includes payload', () => {
+    const err = new SerializationError({ bad: 'data' });
     expect(err).toBeInstanceOf(RocketMQError);
     expect(err.name).toBe('SerializationError');
+    expect(err.message).toBe('Serialization error for payload: {"bad":"data"}');
+    expect(err.payload).toEqual({ bad: 'data' });
   });
 
   it('preserves cause', () => {
-    const cause = new SyntaxError('Unexpected token');
-    const err = new SerializationError('parse failed', cause);
+    const cause = new Error('parse error');
+    const err = new SerializationError('data', cause);
     expect(err.cause).toBe(cause);
   });
 });

package/src/errors.ts

@@ -34,9 +34,10 @@ export class QueueError extends RocketMQError {
 export class PublishError extends RocketMQError {
   constructor(
     public readonly queue: string,
+    public readonly payload: unknown,
     cause?: unknown,
   ) {
-    super(`Failed to publish to '${queue}'`, cause);
+    super(`Failed to publish payload to '${queue}': ${JSON.stringify(payload)}`, cause);
     this.name = 'PublishError';
   }
 }
@@ -49,8 +50,11 @@ export class ConsumeError extends RocketMQError {
 }
 
 export class SerializationError extends RocketMQError {
-  constructor(message: string, cause?: unknown) {
-    super(message, cause);
+  constructor(
+    public readonly payload: unknown,
+    cause?: unknown,
+  ) {
+    super(`Serialization error for payload: ${JSON.stringify(payload)}`, cause);
     this.name = 'SerializationError';
   }
 }
@@ -62,6 +66,39 @@ export class SchemaError extends RocketMQError {
   }
 }
 
+/**
+ * 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' }]
+ *     }
+ *   }
+ */
+export class SchemaValidationError extends SchemaError {
+  constructor(
+    public readonly code: string,
+    public readonly queue: string,
+    public readonly fields: ReadonlyArray<{
+      readonly name: string;
+      readonly expected: string;
+      readonly got: string;
+    }>,
+    message: string,
+    cause?: unknown,
+  ) {
+    super(message, cause);
+    this.name = 'SchemaValidationError';
+  }
+}
+
 export class TimeoutError extends RocketMQError {
   constructor(message: string, cause?: unknown) {
     super(message, cause);

package/src/index.ts

@@ -2,6 +2,18 @@
 export { Schema, Field } from '@rocketmq/schema';
 export type { ProtoType, FieldMeta, SchemaEntry } from '@rocketmq/schema';
 
+// Re-export Zod schema utilities so users can use either style
+export {
+  zodToProto,
+  zodToFields,
+  isZodSchemaInput,
+  isRawZodObject,
+  type ZodSchemaInput,
+} from '@rocketmq/zod';
+
+// Re-export schema resolver types
+export { type SchemaInput } from './schema-resolver.js';
+
 // Re-export serializer interface for custom implementations
 export type { Serializer } from '@rocketmq/serializer';
 
@@ -9,7 +21,13 @@ export type { Serializer } from '@rocketmq/serializer';
 export type { ConsumeMessage } from '@rocketmq/amqp';
 
 // Core API
-export { connect, RocketMQ, type RocketOptions } from './client.js';
+export {
+  connect,
+  RocketMQ,
+  type RocketOptions,
+  type RocketAssertQueueOptions,
+  type RocketConsumeOptions,
+} from './client.js';
 export { QueueHandle } from './queue-handle.js';
 
 // Errors
@@ -21,5 +39,17 @@ export {
   ConsumeError,
   SerializationError,
   SchemaError,
+  SchemaValidationError,
   TimeoutError,
 } from './errors.js';
+
+// Error codes and parser for structured broker errors
+export { BrokerErrorCode } from './error-codes.js';
+export {
+  parseBrokerError,
+  extractReplyText,
+  formatBrokerError,
+  protoToTsType,
+  type BrokerErrorPayload,
+  type FieldErrorDetail,
+} from './error-parser.js';

package/src/queue-handle.test.ts

@@ -1,29 +1,10 @@
-/**
- * Tests for QueueHandle<T>.
- *
- * Uses FakeAmqpChannel and FakeSerializer mocks.
- * Covers: send (valid, invalid, serialization error),
- * consume (success, deserialization error, consume failure).
- */
-
 import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { QueueHandle } from './queue-handle.js';
-import { SchemaRegistry } from '@rocketmq/schema';
-import type { SchemaEntry } from '@rocketmq/schema';
-import type { Serializer } from '@rocketmq/serializer';
-import { PublishError, ConsumeError } from './errors.js';
+import type { RocketMQ } from './client.js';
 
-/** Named fake per user rules. */
-class FakeAmqpChannel {
+class FakeRocketMQ {
   sendToQueue = vi.fn().mockReturnValue(true);
-  consume = vi.fn().mockResolvedValue({ consumerTag: 'tag-1' });
-}
-
-/** Named fake serializer. */
-class FakeSerializer implements Serializer {
-  readonly contentType = 'application/json';
-  serialize = vi.fn((v: unknown) => Buffer.from(JSON.stringify(v)));
-  deserialize = vi.fn((buf: Buffer) => JSON.parse(buf.toString()));
+  consume = vi.fn().mockResolvedValue('tag-1');
 }
 
 interface TestMsg {
@@ -31,60 +12,32 @@ interface TestMsg {
   qty: number;
 }
 
+class TestSchema {}
+
 describe('QueueHandle', () => {
-  let registry: SchemaRegistry;
-  let channel: FakeAmqpChannel;
-  let serializer: FakeSerializer;
+  let client: FakeRocketMQ;
   let handle: QueueHandle<TestMsg>;
 
   beforeEach(() => {
-    registry = new SchemaRegistry();
-    channel = new FakeAmqpChannel();
-    serializer = new FakeSerializer();
-
-    const entry: SchemaEntry = {
-      ctor: class {},
-      name: 'TestMsg',
-      fields: [
-        { name: 'id', protoType: 'string', number: 1 },
-        { name: 'qty', protoType: 'int32', number: 2 },
-      ],
-    };
-    registry.register('test-queue', entry);
-
-    handle = new QueueHandle<TestMsg>('test-queue', channel as never, registry, serializer);
+    client = new FakeRocketMQ();
+    handle = new QueueHandle<TestMsg>('test-queue', client as unknown as RocketMQ, TestSchema);
   });
 
   describe('send', () => {
     it('serializes and sends a payload', () => {
       const result = handle.send({ id: '1', qty: 5 });
       expect(result).toBe(true);
-      expect(serializer.serialize).toHaveBeenCalledWith({ id: '1', qty: 5 });
-      expect(channel.sendToQueue).toHaveBeenCalledWith(
-        'test-queue',
-        expect.any(Buffer),
-        expect.objectContaining({
-          contentType: 'application/json',
-          persistent: true,
-        }),
-      );
+      expect(client.sendToQueue).toHaveBeenCalledWith('test-queue', { id: '1', qty: 5 }, undefined);
     });
 
     it('passes custom publish options', () => {
       handle.send({ id: '1', qty: 5 }, { priority: 5 });
-      expect(channel.sendToQueue).toHaveBeenCalledWith(
+      expect(client.sendToQueue).toHaveBeenCalledWith(
         'test-queue',
-        expect.any(Buffer),
-        expect.objectContaining({ priority: 5 }),
+        { id: '1', qty: 5 },
+        { priority: 5 },
       );
     });
-
-    it('throws PublishError when channel.sendToQueue throws', () => {
-      channel.sendToQueue.mockImplementation(() => {
-        throw new Error('channel closed');
-      });
-      expect(() => handle.send({ id: '1', qty: 5 })).toThrow(PublishError);
-    });
   });
 
   describe('consume', () => {
@@ -92,94 +45,15 @@ describe('QueueHandle', () => {
       const handler = vi.fn();
       const tag = await handle.consume(handler);
       expect(tag).toBe('tag-1');
-      expect(channel.consume).toHaveBeenCalledWith('test-queue', expect.any(Function), {
-        arguments: {},
-      });
-    });
-
-    it('deserializes and calls handler with typed message', async () => {
-      const handler = vi.fn();
-      // Capture the internal callback
-      channel.consume.mockImplementation(async (_q: string, cb: Function) => {
-        const raw = {
-          content: Buffer.from(JSON.stringify({ id: 'x', qty: 3 })),
-          fields: {},
-          properties: {},
-        };
-        cb(raw);
-        return { consumerTag: 'tag-2' };
-      });
-
-      await handle.consume(handler);
-      expect(handler).toHaveBeenCalledWith(
-        { id: 'x', qty: 3 },
-        expect.objectContaining({ content: expect.any(Buffer) }),
-      );
-    });
-
-    it('ignores null messages', async () => {
-      const handler = vi.fn();
-      channel.consume.mockImplementation(async (_q: string, cb: Function) => {
-        cb(null);
-        return { consumerTag: 'tag-3' };
-      });
-
-      await handle.consume(handler);
-      expect(handler).not.toHaveBeenCalled();
-    });
-
-    it('logs deserialization errors without crashing', async () => {
-      const handler = vi.fn();
-      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
-
-      serializer.deserialize.mockImplementation(() => {
-        throw new SyntaxError('bad json');
-      });
-
-      channel.consume.mockImplementation(async (_q: string, cb: Function) => {
-        cb({ content: Buffer.from('not json'), fields: {}, properties: {} });
-        return { consumerTag: 'tag-4' };
-      });
-
-      await handle.consume(handler);
-      expect(handler).not.toHaveBeenCalled();
-      expect(consoleSpy).toHaveBeenCalledWith(
-        expect.stringContaining('deserialization error'),
-        expect.any(SyntaxError),
-      );
-      consoleSpy.mockRestore();
-    });
-
-    it('throws ConsumeError when channel.consume rejects', async () => {
-      channel.consume.mockRejectedValue(new Error('NOT_FOUND'));
-      const handler = vi.fn();
-      await expect(handle.consume(handler)).rejects.toThrow(ConsumeError);
+      expect(client.consume).toHaveBeenCalledWith('test-queue', TestSchema, handler, undefined);
     });
 
     it('passes consume options through', async () => {
       const handler = vi.fn();
       await handle.consume(handler, { noAck: true });
-      expect(channel.consume).toHaveBeenCalledWith('test-queue', expect.any(Function), {
+      expect(client.consume).toHaveBeenCalledWith('test-queue', TestSchema, handler, {
         noAck: true,
-        arguments: {},
       });
     });
   });
 });
-
-describe('QueueHandle without schema', () => {
-  it('sends without errors when no schema registered', () => {
-    const registry = new SchemaRegistry();
-    const channel = new FakeAmqpChannel();
-    const serializer = new FakeSerializer();
-    const handle = new QueueHandle<Record<string, unknown>>(
-      'unregistered',
-      channel as never,
-      registry,
-      serializer,
-    );
-
-    const result = handle.send({ anything: 'goes' });
-    expect(result).toBe(true);
-  });
-});

package/src/queue-handle.ts

@@ -11,18 +11,15 @@
  *   await orders.consume((msg) => console.log(msg.id));
  */
 
-import type { AmqpChannel, ConsumeMessage, ConsumeOptions, PublishOptions } from '@rocketmq/amqp';
-import type { SchemaRegistry } from '@rocketmq/schema';
-import type { Serializer } from '@rocketmq/serializer';
-import { toProto } from '@rocketmq/protobuf';
-import { PublishError, ConsumeError } from './errors.js';
+import type { ConsumeOptions, PublishOptions } from '@rocketmq/amqp';
+import type { RocketMQ, TypedConsumeHandler } from './client.js';
+import type { SchemaInput } from './schema-resolver.js';
 
 export class QueueHandle<T> {
   constructor(
     private readonly queueName: string,
-    private readonly channel: AmqpChannel,
-    private readonly registry: SchemaRegistry,
-    private readonly serializer: Serializer,
+    private readonly client: RocketMQ,
+    private readonly schema: SchemaInput<T>,
   ) {}
 
   /**
@@ -31,16 +28,7 @@ export class QueueHandle<T> {
    * Pipeline: serialize → send. Validation is broker-side.
    */
   send(payload: T, opts?: PublishOptions): boolean {
-    try {
-      const buf = this.serializer.serialize(payload);
-      return this.channel.sendToQueue(this.queueName, buf, {
-        contentType: this.serializer.contentType,
-        persistent: true,
-        ...opts,
-      });
-    } catch (err) {
-      throw new PublishError(this.queueName, err);
-    }
+    return this.client.sendToQueue(this.queueName, payload as Record<string, unknown>, opts);
   }
 
   /**
@@ -50,53 +38,7 @@ export 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.
    */
-  async consume(
-    handler: (msg: T, raw: ConsumeMessage) => void,
-    opts?: ConsumeOptions,
-  ): Promise<string> {
-    const consumerArgs = this.buildConsumerSchemaArgs();
-
-    try {
-      const reply = await this.channel.consume(
-        this.queueName,
-        (raw) => {
-          if (!raw) return;
-          try {
-            const body = this.serializer.deserialize(raw.content) as T;
-            handler(body, raw);
-          } catch (err) {
-            // WHY: log instead of throw to keep the consumer loop alive
-            console.error(`[rocketmq] deserialization error on queue '${this.queueName}':`, err);
-          }
-        },
-        {
-          ...opts,
-          arguments: {
-            ...opts?.arguments,
-            ...consumerArgs,
-          },
-        },
-      );
-      return reply.consumerTag;
-    } catch (err) {
-      throw new ConsumeError(`Failed to consume from queue '${this.queueName}'`, err);
-    }
-  }
-
-  /** Builds AMQP arguments for consumer schema subset checking. */
-  private buildConsumerSchemaArgs(): Record<string, string> {
-    const meta = this.registry.lookup(this.queueName);
-    if (!meta) return {};
-
-    try {
-      const proto = toProto(meta.ctor);
-      return {
-        'x-consumer-schema': proto,
-        'x-consumer-schema-message': meta.name,
-      };
-    } catch {
-      // WHY: ctor may lack @Field() decorators (e.g. untyped consumers)
-      return {};
-    }
+  async consume(handler: TypedConsumeHandler<T>, opts?: ConsumeOptions): Promise<string> {
+    return this.client.consume(this.queueName, this.schema, handler, opts);
   }
 }