@rocketmq/core 0.1.0

package/src/errors.test.ts

@@ -0,0 +1,132 @@
+/**
+ * Tests for the error hierarchy.
+ *
+ * Covers every error class: construction, message formatting,
+ * name property, cause chaining, and custom properties.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  RocketMQError,
+  ConnectionError,
+  QueueError,
+  PublishError,
+  ConsumeError,
+  SerializationError,
+  SchemaError,
+  TimeoutError,
+} from './errors.js';
+
+describe('RocketMQError', () => {
+  it('sets message and name', () => {
+    const err = new RocketMQError('test error');
+    expect(err.message).toBe('test error');
+    expect(err.name).toBe('RocketMQError');
+    expect(err).toBeInstanceOf(Error);
+  });
+
+  it('preserves cause', () => {
+    const cause = new Error('root cause');
+    const err = new RocketMQError('wrapped', cause);
+    expect(err.cause).toBe(cause);
+  });
+});
+
+describe('ConnectionError', () => {
+  it('extends RocketMQError', () => {
+    const err = new ConnectionError('conn failed');
+    expect(err).toBeInstanceOf(RocketMQError);
+    expect(err.name).toBe('ConnectionError');
+  });
+
+  it('preserves cause', () => {
+    const cause = new Error('ECONNREFUSED');
+    const err = new ConnectionError('failed', cause);
+    expect(err.cause).toBe(cause);
+  });
+});
+
+describe('QueueError', () => {
+  it('extends RocketMQError', () => {
+    const err = new QueueError('queue fail');
+    expect(err).toBeInstanceOf(RocketMQError);
+    expect(err.name).toBe('QueueError');
+  });
+
+  it('preserves cause', () => {
+    const cause = new Error('PRECONDITION_FAILED');
+    const err = new QueueError('failed', cause);
+    expect(err.cause).toBe(cause);
+  });
+});
+
+describe('PublishError', () => {
+  it('formats message with queue name', () => {
+    const err = new PublishError('orders');
+    expect(err.message).toBe("Failed to publish to 'orders'");
+    expect(err.queue).toBe('orders');
+    expect(err.name).toBe('PublishError');
+  });
+
+  it('preserves cause', () => {
+    const cause = new Error('channel closed');
+    const err = new PublishError('q', cause);
+    expect(err.cause).toBe(cause);
+  });
+});
+
+describe('ConsumeError', () => {
+  it('extends RocketMQError', () => {
+    const err = new ConsumeError('consume fail');
+    expect(err).toBeInstanceOf(RocketMQError);
+    expect(err.name).toBe('ConsumeError');
+  });
+
+  it('preserves cause', () => {
+    const cause = new Error('NOT_FOUND');
+    const err = new ConsumeError('failed', cause);
+    expect(err.cause).toBe(cause);
+  });
+});
+
+describe('SerializationError', () => {
+  it('extends RocketMQError', () => {
+    const err = new SerializationError('bad json');
+    expect(err).toBeInstanceOf(RocketMQError);
+    expect(err.name).toBe('SerializationError');
+  });
+
+  it('preserves cause', () => {
+    const cause = new SyntaxError('Unexpected token');
+    const err = new SerializationError('parse failed', cause);
+    expect(err.cause).toBe(cause);
+  });
+});
+
+describe('SchemaError', () => {
+  it('extends RocketMQError', () => {
+    const err = new SchemaError('no fields');
+    expect(err).toBeInstanceOf(RocketMQError);
+    expect(err.name).toBe('SchemaError');
+  });
+
+  it('preserves cause', () => {
+    const cause = new Error('compile failed');
+    const err = new SchemaError('schema issue', cause);
+    expect(err.cause).toBe(cause);
+  });
+});
+
+describe('TimeoutError', () => {
+  it('extends RocketMQError', () => {
+    const err = new TimeoutError('timed out after 5s');
+    expect(err).toBeInstanceOf(RocketMQError);
+    expect(err.name).toBe('TimeoutError');
+  });
+
+  it('preserves cause', () => {
+    const cause = new Error('deadline');
+    const err = new TimeoutError('timeout', cause);
+    expect(err.cause).toBe(cause);
+  });
+});

package/src/errors.ts

@@ -0,0 +1,70 @@
+/**
+ * Error hierarchy for the RocketMQ SDK.
+ *
+ * Every error includes the offending context (queue name, schema name, etc.)
+ * and preserves the original cause via the standard `cause` property.
+ *
+ * Usage:
+ *   try { ... } catch (err) {
+ *     if (err instanceof PublishError) console.error(err.queue);
+ *   }
+ */
+
+export class RocketMQError extends Error {
+  constructor(message: string, cause?: unknown) {
+    super(message, { cause });
+    this.name = 'RocketMQError';
+  }
+}
+
+export class ConnectionError extends RocketMQError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause);
+    this.name = 'ConnectionError';
+  }
+}
+
+export class QueueError extends RocketMQError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause);
+    this.name = 'QueueError';
+  }
+}
+
+export class PublishError extends RocketMQError {
+  constructor(
+    public readonly queue: string,
+    cause?: unknown,
+  ) {
+    super(`Failed to publish to '${queue}'`, cause);
+    this.name = 'PublishError';
+  }
+}
+
+export class ConsumeError extends RocketMQError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause);
+    this.name = 'ConsumeError';
+  }
+}
+
+export class SerializationError extends RocketMQError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause);
+    this.name = 'SerializationError';
+  }
+}
+
+export class SchemaError extends RocketMQError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause);
+    this.name = 'SchemaError';
+  }
+}
+
+export class TimeoutError extends RocketMQError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause);
+    this.name = 'TimeoutError';
+  }
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+// Re-export decorators so users only need one import
+export { Schema, Field } from '@rocketmq/schema';
+export type { ProtoType, FieldMeta, SchemaEntry } from '@rocketmq/schema';
+
+// Re-export serializer interface for custom implementations
+export type { Serializer } from '@rocketmq/serializer';
+
+// Re-export AMQP types needed by consumers
+export type { ConsumeMessage } from '@rocketmq/amqp';
+
+// Core API
+export { connect, RocketMQ, type RocketOptions } from './client.js';
+export { QueueHandle } from './queue-handle.js';
+
+// Errors
+export {
+  RocketMQError,
+  ConnectionError,
+  QueueError,
+  PublishError,
+  ConsumeError,
+  SerializationError,
+  SchemaError,
+  TimeoutError,
+} from './errors.js';

package/src/queue-handle.test.ts

@@ -0,0 +1,185 @@
+/**
+ * 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';
+
+/** Named fake per user rules. */
+class FakeAmqpChannel {
+  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()));
+}
+
+interface TestMsg {
+  id: string;
+  qty: number;
+}
+
+describe('QueueHandle', () => {
+  let registry: SchemaRegistry;
+  let channel: FakeAmqpChannel;
+  let serializer: FakeSerializer;
+  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);
+  });
+
+  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,
+        }),
+      );
+    });
+
+    it('passes custom publish options', () => {
+      handle.send({ id: '1', qty: 5 }, { priority: 5 });
+      expect(channel.sendToQueue).toHaveBeenCalledWith(
+        'test-queue',
+        expect.any(Buffer),
+        expect.objectContaining({ 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', () => {
+    it('subscribes and returns consumer tag', async () => {
+      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);
+    });
+
+    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), {
+        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

@@ -0,0 +1,102 @@
+/**
+ * Typed queue handle — the core DX innovation.
+ *
+ * Wraps a queue name with its schema and serializer so every send()
+ * and consume() call is type-safe at compile time. Runtime validation
+ * is delegated to the broker's compiled proto schema.
+ *
+ * Usage:
+ *   const orders = mq.queue("orders", Order);
+ *   await orders.send({ id: "1", customerId: "c1", qty: 5 });
+ *   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';
+
+export class QueueHandle<T> {
+  constructor(
+    private readonly queueName: string,
+    private readonly channel: AmqpChannel,
+    private readonly registry: SchemaRegistry,
+    private readonly serializer: Serializer,
+  ) {}
+
+  /**
+   * Publishes a typed payload to this queue.
+   *
+   * 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);
+    }
+  }
+
+  /**
+   * Subscribes to this queue with typed message handling.
+   *
+   * Sends the consumer's proto definition to the broker via AMQP
+   * 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 {};
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/tsup.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["esm", "cjs"],
+  dts: true,
+  clean: true,
+});