alepha 0.19.0 → 0.19.2

package/src/mqtt/providers/MqttClientProvider.ts

@@ -1,63 +0,0 @@
-import type { UnSubscribeFn } from "alepha/topic";
-
-/**
- * Abstract MQTT client provider.
- *
- * Low-level MQTT client for publish/subscribe messaging.
- * Analogous to `RedisProvider` — provides the transport layer
- * that higher-level modules like `alepha/topic/mqtt` build on.
- */
-export abstract class MqttClientProvider {
-  /**
-   * Connect to the MQTT broker.
-   */
-  public abstract connect(): Promise<void>;
-
-  /**
-   * Disconnect from the MQTT broker.
-   */
-  public abstract disconnect(): Promise<void>;
-
-  /**
-   * Whether the client is currently connected.
-   */
-  public abstract get isConnected(): boolean;
-
-  /**
-   * Publish a message to an MQTT topic.
-   */
-  public abstract publish(
-    topic: string,
-    message: string,
-    options?: MqttPublishOptions,
-  ): Promise<void>;
-
-  /**
-   * Subscribe to an MQTT topic.
-   * Callback receives the actual topic string as first arg (for wildcard matching).
-   */
-  public abstract subscribe(
-    topic: string,
-    callback: MqttMessageCallback,
-    options?: MqttSubscribeOptions,
-  ): Promise<UnSubscribeFn>;
-
-  /**
-   * Unsubscribe from an MQTT topic.
-   */
-  public abstract unsubscribe(topic: string): Promise<void>;
-}
-
-export interface MqttPublishOptions {
-  qos?: 0 | 1 | 2;
-  retain?: boolean;
-}
-
-export interface MqttSubscribeOptions {
-  qos?: 0 | 1 | 2;
-}
-
-export type MqttMessageCallback = (
-  topic: string,
-  payload: string,
-) => void | Promise<void>;

package/src/mqtt/providers/MqttJsClientProvider.spec.ts

@@ -1,165 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { Alepha } from "alepha";
-import { describe, it } from "vitest";
-import { MqttClientProvider } from "./MqttClientProvider.ts";
-import { MqttJsClientProvider, mqttOptions } from "./MqttJsClientProvider.ts";
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-/**
- * Creates an Alepha instance wired with MqttJsClientProvider.
- */
-const createApp = () => {
-  return Alepha.create().with({
-    provide: MqttClientProvider,
-    use: MqttJsClientProvider,
-  });
-};
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-describe("MqttJsClientProvider", () => {
-  it("should connect on start and disconnect on stop", async ({ expect }) => {
-    const alepha = createApp();
-    const mqtt = alepha.inject(MqttJsClientProvider);
-
-    expect(mqtt.isConnected).toBe(false);
-
-    await alepha.start();
-    expect(mqtt.isConnected).toBe(true);
-
-    await alepha.stop();
-    expect(mqtt.isConnected).toBe(false);
-  });
-
-  it("should publish and receive a message", async ({ expect }) => {
-    const topic = `test/mqtt-client/${randomUUID()}/basic`;
-    const received: string[] = [];
-
-    const alepha = createApp();
-    const mqtt = alepha.inject(MqttJsClientProvider);
-    await alepha.start();
-
-    await mqtt.subscribe(topic, (_t, payload) => {
-      received.push(payload);
-    });
-
-    await mqtt.publish(topic, "hello");
-
-    await expect.poll(() => received.length, { timeout: 5000 }).toBe(1);
-    expect(received[0]).toBe("hello");
-
-    await alepha.stop();
-  });
-
-  it("should support wildcard subscriptions with + single-level wildcard", async ({
-    expect,
-  }) => {
-    const uid = randomUUID();
-    const pattern = `test/mqtt-client/${uid}/+/data`;
-    const received: Array<{ topic: string; payload: string }> = [];
-
-    const alepha = createApp();
-    const mqtt = alepha.inject(MqttJsClientProvider);
-    await alepha.start();
-
-    await mqtt.subscribe(pattern, (t, payload) => {
-      received.push({ topic: t, payload });
-    });
-
-    await mqtt.publish(`test/mqtt-client/${uid}/device1/data`, "msg1");
-    await mqtt.publish(`test/mqtt-client/${uid}/device2/data`, "msg2");
-
-    await expect.poll(() => received.length, { timeout: 5000 }).toBe(2);
-
-    const topics = received.map((r) => r.topic);
-    expect(topics).toContain(`test/mqtt-client/${uid}/device1/data`);
-    expect(topics).toContain(`test/mqtt-client/${uid}/device2/data`);
-
-    const payloads = received.map((r) => r.payload);
-    expect(payloads).toContain("msg1");
-    expect(payloads).toContain("msg2");
-
-    await alepha.stop();
-  });
-
-  it("should not auto-connect when lazy: true", async ({ expect }) => {
-    const alepha = createApp();
-    alepha.store.mut(mqttOptions, () => ({ keepalive: 60, lazy: true }));
-
-    const mqtt = alepha.inject(MqttJsClientProvider);
-
-    await alepha.start();
-    expect(mqtt.isConnected).toBe(false);
-
-    // publish should trigger lazy connection
-    const topic = `test/mqtt-client/${randomUUID()}/lazy`;
-    await mqtt.publish(topic, "wake-up");
-    expect(mqtt.isConnected).toBe(true);
-
-    await alepha.stop();
-  });
-
-  it("should stop receiving messages after unsubscribe", async ({ expect }) => {
-    const topic = `test/mqtt-client/${randomUUID()}/unsub`;
-    const received: string[] = [];
-
-    const alepha = createApp();
-    const mqtt = alepha.inject(MqttJsClientProvider);
-    await alepha.start();
-
-    const unsubscribe = await mqtt.subscribe(topic, (_t, payload) => {
-      received.push(payload);
-    });
-
-    await mqtt.publish(topic, "before-unsub");
-    await expect.poll(() => received.length, { timeout: 5000 }).toBe(1);
-
-    await unsubscribe();
-
-    await mqtt.publish(topic, "after-unsub");
-
-    // Give a short window to confirm the second message does NOT arrive.
-    await new Promise<void>((resolve) => setTimeout(resolve, 200));
-    expect(received.length).toBe(1);
-
-    await alepha.stop();
-  });
-
-  it("should deliver a retained message to a late subscriber", {
-    retry: 3,
-  }, async ({ expect }) => {
-    const topic = `test/mqtt-client/${randomUUID()}/retain`;
-    const received: string[] = [];
-
-    // Use two separate clients: one to publish, another to subscribe.
-    // This mirrors real-world usage and avoids same-client delivery races.
-    const publisher = createApp();
-    const subscriber = createApp();
-    const pubMqtt = publisher.inject(MqttJsClientProvider);
-    const subMqtt = subscriber.inject(MqttJsClientProvider);
-    await publisher.start();
-
-    // Publish with retain + QoS 1 so the broker ACKs storage before resolving.
-    await pubMqtt.publish(topic, "retained-value", { retain: true, qos: 1 });
-
-    // Start the subscriber AFTER the publish is confirmed.
-    await subscriber.start();
-    await subMqtt.subscribe(
-      topic,
-      (_t, payload) => {
-        received.push(payload);
-      },
-      { qos: 1 },
-    );
-
-    await expect.poll(() => received.length, { timeout: 5000 }).toBe(1);
-    expect(received[0]).toBe("retained-value");
-
-    // Clean up: clear the retained message from the broker.
-    await pubMqtt.publish(topic, "", { retain: true });
-
-    await publisher.stop();
-    await subscriber.stop();
-  });
-});

package/src/mqtt/providers/MqttJsClientProvider.ts

@@ -1,309 +0,0 @@
-import {
-  $atom,
-  $env,
-  $hook,
-  $inject,
-  $use,
-  Alepha,
-  AlephaError,
-  type Static,
-  t,
-} from "alepha";
-import { $logger } from "alepha/logger";
-import type { UnSubscribeFn } from "alepha/topic";
-import type { MqttClient } from "mqtt";
-import {
-  MqttClientProvider,
-  type MqttMessageCallback,
-  type MqttPublishOptions,
-  type MqttSubscribeOptions,
-} from "./MqttClientProvider.ts";
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-const envSchema = t.object({
-  MQTT_BROKER_URL: t.text({
-    default: "mqtt://localhost:1883",
-    description: "MQTT broker connection URL",
-  }),
-});
-
-declare module "alepha" {
-  interface Env extends Partial<Static<typeof envSchema>> {}
-}
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-/**
- * MQTT client configuration atom.
- */
-export const mqttOptions = $atom({
-  name: "alepha.mqtt.options",
-  schema: t.object({
-    clientId: t.optional(
-      t.text({
-        description: "MQTT client identifier. Auto-generated if omitted.",
-      }),
-    ),
-    keepalive: t.number({
-      default: 60,
-      description: "Keepalive interval in seconds.",
-    }),
-    lazy: t.boolean({
-      default: false,
-      description:
-        "When true, the connection is deferred until the first publish or subscribe.",
-    }),
-  }),
-  default: {
-    keepalive: 60,
-    lazy: false,
-  },
-});
-
-export type MqttOptions = Static<typeof mqttOptions.schema>;
-
-declare module "alepha" {
-  interface State {
-    [mqttOptions.key]: MqttOptions;
-  }
-}
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-/**
- * MQTT client provider backed by the `mqtt` npm package (mqtt.js).
- *
- * Wraps `mqtt.connectAsync` and exposes a lifecycle-managed client.
- *
- * @example
- * ```ts
- * // Set MQTT_BROKER_URL environment variable (default: mqtt://localhost:1883)
- * // MQTT_BROKER_URL=mqtt://broker.example.com:1883
- *
- * // Or configure programmatically
- * alepha.with({
- *   provide: MqttClientProvider,
- *   use: MqttJsClientProvider,
- * });
- * ```
- */
-export class MqttJsClientProvider extends MqttClientProvider {
-  protected readonly log = $logger();
-  protected readonly alepha = $inject(Alepha);
-  protected readonly env = $env(envSchema);
-  protected readonly options = $use(mqttOptions);
-
-  protected client: MqttClient | undefined;
-
-  /**
-   * Subscriptions map: pattern → set of callbacks.
-   */
-  protected subscriptions = new Map<string, Set<MqttMessageCallback>>();
-
-  // -----------------------------------------------------------------------------------------------------------------
-
-  protected readonly start = $hook({
-    on: "start",
-    handler: async () => {
-      if (!this.options.lazy) {
-        await this.connect();
-      }
-    },
-  });
-
-  protected readonly stop = $hook({
-    on: "stop",
-    handler: async () => {
-      if (this.client) {
-        await this.disconnect();
-      }
-    },
-  });
-
-  // -----------------------------------------------------------------------------------------------------------------
-
-  public override get isConnected(): boolean {
-    return this.client?.connected ?? false;
-  }
-
-  /**
-   * Connect to the MQTT broker.
-   */
-  public override async connect(): Promise<void> {
-    const url = this.env.MQTT_BROKER_URL;
-    this.log.debug(`Connecting to ${url}...`);
-
-    const { connectAsync } = await import("mqtt");
-
-    this.client = await connectAsync(url, {
-      clientId: this.options.clientId,
-      keepalive: this.options.keepalive,
-    });
-
-    this.client.on("error", (error) => {
-      if (this.alepha.isStarted()) {
-        this.log.error("MQTT client error", error);
-      }
-    });
-
-    this.client.on("message", (receivedTopic, payload) => {
-      const message = payload.toString();
-
-      for (const [pattern, callbacks] of this.subscriptions.entries()) {
-        if (this.topicMatches(pattern, receivedTopic)) {
-          for (const callback of callbacks) {
-            Promise.resolve(callback(receivedTopic, message)).catch((error) => {
-              this.log.error(
-                `Error in MQTT message handler for topic '${receivedTopic}'`,
-                error,
-              );
-            });
-          }
-        }
-      }
-    });
-
-    this.log.info("MQTT connection OK");
-  }
-
-  /**
-   * Disconnect from the MQTT broker.
-   */
-  public override async disconnect(): Promise<void> {
-    if (!this.client) {
-      return;
-    }
-
-    this.log.debug("Disconnecting...");
-    await this.client.endAsync();
-    this.client = undefined;
-    this.subscriptions.clear();
-    this.log.info("MQTT connection closed");
-  }
-
-  /**
-   * Publish a message to an MQTT topic.
-   */
-  public override async publish(
-    topic: string,
-    message: string,
-    options?: MqttPublishOptions,
-  ): Promise<void> {
-    await this.ensureConnected();
-    await this.client!.publishAsync(topic, message, {
-      qos: options?.qos,
-      retain: options?.retain,
-    });
-  }
-
-  /**
-   * Subscribe to an MQTT topic pattern.
-   *
-   * Supports MQTT wildcards: `+` for a single level, `#` for multiple levels.
-   * The callback receives the actual received topic as the first argument.
-   */
-  public override async subscribe(
-    topic: string,
-    callback: MqttMessageCallback,
-    options?: MqttSubscribeOptions,
-  ): Promise<UnSubscribeFn> {
-    await this.ensureConnected();
-
-    if (!this.subscriptions.has(topic)) {
-      this.subscriptions.set(topic, new Set());
-      await this.client!.subscribeAsync(topic, { qos: options?.qos ?? 0 });
-    }
-
-    this.subscriptions.get(topic)!.add(callback);
-
-    return async () => {
-      await this.unsubscribeCallback(topic, callback);
-    };
-  }
-
-  /**
-   * Unsubscribe all callbacks from an MQTT topic pattern.
-   */
-  public override async unsubscribe(topic: string): Promise<void> {
-    if (!this.subscriptions.has(topic)) {
-      return;
-    }
-
-    this.subscriptions.delete(topic);
-
-    if (this.client?.connected) {
-      await this.client.unsubscribeAsync(topic);
-    }
-  }
-
-  // -----------------------------------------------------------------------------------------------------------------
-
-  /**
-   * Ensure the client is connected, connecting lazily if needed.
-   */
-  protected async ensureConnected(): Promise<void> {
-    if (!this.client || !this.client.connected) {
-      if (!this.options.lazy) {
-        throw new AlephaError("MQTT client is not connected");
-      }
-
-      await this.connect();
-    }
-  }
-
-  /**
-   * Remove a single callback from a topic subscription.
-   * Unsubscribes from the broker when no callbacks remain.
-   */
-  protected async unsubscribeCallback(
-    topic: string,
-    callback: MqttMessageCallback,
-  ): Promise<void> {
-    const callbacks = this.subscriptions.get(topic);
-    if (!callbacks) {
-      return;
-    }
-
-    callbacks.delete(callback);
-
-    if (callbacks.size === 0) {
-      await this.unsubscribe(topic);
-    }
-  }
-
-  /**
-   * Test whether a received MQTT topic matches a subscription pattern.
-   *
-   * Supports the two MQTT wildcard characters:
-   * - `+` matches exactly one topic level
-   * - `#` matches any number of remaining levels (must be the last segment)
-   */
-  protected topicMatches(pattern: string, topic: string): boolean {
-    if (pattern === topic) {
-      return true;
-    }
-
-    const patternParts = pattern.split("/");
-    const topicParts = topic.split("/");
-
-    for (let i = 0; i < patternParts.length; i++) {
-      const p = patternParts[i];
-
-      if (p === "#") {
-        // Multi-level wildcard — matches everything remaining.
-        return true;
-      }
-
-      if (i >= topicParts.length) {
-        return false;
-      }
-
-      if (p !== "+" && p !== topicParts[i]) {
-        return false;
-      }
-    }
-
-    return patternParts.length === topicParts.length;
-  }
-}

package/src/topic/mqtt/index.ts

@@ -1,30 +0,0 @@
-import { $module, type Alepha } from "alepha";
-import { AlephaTopic, TopicProvider } from "alepha/topic";
-import { MqttTopicProvider } from "./providers/MqttTopicProvider.ts";
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-export * from "./providers/MqttTopicProvider.ts";
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-/**
- * Plugin for Alepha Topic that provides MQTT pub/sub capabilities.
- *
- * Users must register `AlephaMqtt` separately for the MQTT client transport.
- *
- * @see {@link MqttTopicProvider}
- * @module alepha.topic.mqtt
- */
-export const AlephaTopicMqtt = $module({
-  name: "alepha.topic.mqtt",
-  services: [MqttTopicProvider],
-  register: (alepha: Alepha): Alepha =>
-    alepha
-      .with({
-        optional: true,
-        provide: TopicProvider,
-        use: MqttTopicProvider,
-      })
-      .with(AlephaTopic),
-});