@fedify/redis 0.4.0 → 1.8.0-pr.278.944

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright 2024 Hong Minhee
+Copyright 2024–2025 Hong Minhee
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

package/README.md

@@ -40,60 +40,10 @@ const federation = createFederation({
 Installation
 ------------
 
-### Deno
-
 ~~~~ sh
-deno add @fedify/redis
+deno add jsr:@fedify/redis  # Deno
+npm  add     @fedify/redis  # npm
+pnpm add     @fedify/redis  # pnpm
+yarn add     @fedify/redis  # Yarn
+bun  add     @fedify/redis  # Bun
 ~~~~
-
-### Node.js
-
-~~~~ sh
-npm install @fedify/redis
-~~~~
-
-### Bun
-
-~~~~ sh
-bun add @fedify/redis
-~~~~
-
-
-Changelog
----------
-
-### Version 0.4.0
-
-Released on March 28, 2025.
-
- -  Added `RedisMessageQueue.enqueueMany()` method for efficiently enqueueing
-    multiple messages in a single transaction.
-
- -  Updated *@js-temporal/polyfill* to 0.5.0 for Node.js and Bun. On Deno,
-    there is no change because the polyfill is not used.
-
-### Version 0.3.0
-
-Released on October 4, 2024.
-
- -  Polling is now more efficient.
- -  Renamed `RedisMessageQueueOptions.loopInterval` option to `pollInterval`
-    option.
-
-### Version 0.2.0
-
-Released on September 26, 2024.
-
- -  Let `RedisMessageQueue` follow up the latest `MessageQueue` interface,
-    which was updated in Fedify 1.0.0.
- -  Added some example code.
-
-### Version 0.1.1
-
-Released on June 22, 2024.
-
- -  Exported `@fedify/redis/mq` module.
-
-### Version 0.1.0
-
-Initial release.  Released on June 22, 2024.

package/dist/codec.d.ts

@@ -0,0 +1,51 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { Buffer } from "node:buffer";
+
+//#region codec.d.ts
+/**
+ * Encode and decodes JavaScript objects to and from binary data.
+ */
+interface Codec {
+  /**
+   * Encodes a JavaScript object to binary data.
+   * @param value The JavaScript object to encode.
+   * @returns The encoded binary data.
+   * @throws {EncodingError} If the JavaScript object cannot be encoded.
+   */
+  encode(value: unknown): Buffer;
+  /**
+   * Decodes a JavaScript object from binary data.
+   * @param encoded The binary data to decode.
+   * @returns The decoded JavaScript object.
+   * @throws {DecodingError} If the binary data is invalid.
+   */
+  decode(encoded: Buffer): unknown;
+}
+/**
+ * An error that occurs when encoding or decoding data.
+ */
+declare class CodecError extends Error {
+  constructor(message: string);
+}
+/**
+ * An error that occurs when encoding data.
+ */
+declare class EncodingError extends CodecError {
+  constructor(message: string);
+}
+/**
+ * An error that occurs when decoding data.
+ */
+declare class DecodingError extends CodecError {
+  constructor(message: string);
+}
+/**
+ * A codec that encodes and decodes JavaScript objects to and from JSON.
+ */
+declare class JsonCodec implements Codec {
+  #private;
+  encode(value: unknown): Buffer;
+  decode(encoded: Buffer): unknown;
+}
+//#endregion
+export { Codec, CodecError, DecodingError, EncodingError, JsonCodec };

package/dist/codec.js

@@ -0,0 +1,62 @@
+
+      import { Temporal } from "@js-temporal/polyfill";
+    
+import { Buffer } from "node:buffer";
+
+//#region codec.ts
+/**
+* An error that occurs when encoding or decoding data.
+*/
+var CodecError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "CodecError";
+	}
+};
+/**
+* An error that occurs when encoding data.
+*/
+var EncodingError = class extends CodecError {
+	constructor(message) {
+		super(message);
+		this.name = "EncodingError";
+	}
+};
+/**
+* An error that occurs when decoding data.
+*/
+var DecodingError = class extends CodecError {
+	constructor(message) {
+		super(message);
+		this.name = "DecodingError";
+	}
+};
+/**
+* A codec that encodes and decodes JavaScript objects to and from JSON.
+*/
+var JsonCodec = class {
+	#textEncoder = new TextEncoder();
+	#textDecoder = new TextDecoder();
+	encode(value) {
+		let json;
+		try {
+			json = JSON.stringify(value);
+		} catch (e) {
+			if (e instanceof TypeError) throw new EncodingError(e.message);
+			throw e;
+		}
+		return Buffer.from(this.#textEncoder.encode(json));
+	}
+	decode(encoded) {
+		const json = this.#textDecoder.decode(encoded);
+		try {
+			return JSON.parse(json);
+		} catch (e) {
+			if (e instanceof SyntaxError) throw new DecodingError(e.message);
+			throw e;
+		}
+	}
+};
+
+//#endregion
+export { CodecError, DecodingError, EncodingError, JsonCodec };

package/dist/kv.d.ts

@@ -0,0 +1,50 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { Codec } from "./codec.js";
+import { KvKey, KvStore, KvStoreSetOptions } from "@fedify/fedify";
+import { Redis, RedisKey } from "ioredis";
+
+//#region kv.d.ts
+/**
+ * Options for {@link RedisKvStore} class.
+ */
+interface RedisKvStoreOptions {
+  /**
+   * The prefix to use for all keys in the key-value store in Redis.
+   * Defaults to `"fedify::"`.
+   */
+  keyPrefix?: RedisKey;
+  /**
+   * The codec to use for encoding and decoding values in the key-value store.
+   * Defaults to {@link JsonCodec}.
+   */
+  codec?: Codec;
+}
+/**
+ * A key-value store that uses Redis as the underlying storage.
+ *
+ * @example
+ * ```ts ignore
+ * import { createFederation } from "@fedify/fedify";
+ * import { RedisKvStore } from "@fedify/redis";
+ * import { Redis } from "ioredis";
+ *
+ * const federation = createFederation({
+ *   // ...
+ *   kv: new RedisKvStore(new Redis()),
+ * });
+ * ```
+ */
+declare class RedisKvStore implements KvStore {
+  #private;
+  /**
+   * Creates a new Redis key-value store.
+   * @param redis The Redis client to use.
+   * @param options The options for the key-value store.
+   */
+  constructor(redis: Redis, options?: RedisKvStoreOptions);
+  get<T = unknown>(key: KvKey): Promise<T | undefined>;
+  set(key: KvKey, value: unknown, options?: KvStoreSetOptions | undefined): Promise<void>;
+  delete(key: KvKey): Promise<void>;
+}
+//#endregion
+export { RedisKvStore, RedisKvStoreOptions };

package/dist/kv.js

@@ -0,0 +1,63 @@
+
+      import { Temporal } from "@js-temporal/polyfill";
+    
+import { JsonCodec } from "./codec.js";
+import { Buffer } from "node:buffer";
+
+//#region kv.ts
+/**
+* A key-value store that uses Redis as the underlying storage.
+*
+* @example
+* ```ts ignore
+* import { createFederation } from "@fedify/fedify";
+* import { RedisKvStore } from "@fedify/redis";
+* import { Redis } from "ioredis";
+*
+* const federation = createFederation({
+*   // ...
+*   kv: new RedisKvStore(new Redis()),
+* });
+* ```
+*/
+var RedisKvStore = class {
+	#redis;
+	#keyPrefix;
+	#codec;
+	#textEncoder = new TextEncoder();
+	/**
+	* Creates a new Redis key-value store.
+	* @param redis The Redis client to use.
+	* @param options The options for the key-value store.
+	*/
+	constructor(redis, options = {}) {
+		this.#redis = redis;
+		this.#keyPrefix = options.keyPrefix ?? "fedify::";
+		this.#codec = options.codec ?? new JsonCodec();
+	}
+	#serializeKey(key) {
+		const suffix = key.map((part) => part.replaceAll(":", "_:")).join("::");
+		if (typeof this.#keyPrefix === "string") return `${this.#keyPrefix}${suffix}`;
+		const suffixBytes = this.#textEncoder.encode(suffix);
+		return Buffer.concat([new Uint8Array(this.#keyPrefix), suffixBytes]);
+	}
+	async get(key) {
+		const serializedKey = this.#serializeKey(key);
+		const encodedValue = await this.#redis.getBuffer(serializedKey);
+		if (encodedValue == null) return void 0;
+		return this.#codec.decode(encodedValue);
+	}
+	async set(key, value, options) {
+		const serializedKey = this.#serializeKey(key);
+		const encodedValue = this.#codec.encode(value);
+		if (options?.ttl != null) await this.#redis.setex(serializedKey, options.ttl.total("second"), encodedValue);
+		else await this.#redis.set(serializedKey, encodedValue);
+	}
+	async delete(key) {
+		const serializedKey = this.#serializeKey(key);
+		await this.#redis.del(serializedKey);
+	}
+};
+
+//#endregion
+export { RedisKvStore };

package/dist/mod.d.ts

@@ -0,0 +1,5 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { Codec, CodecError, DecodingError, EncodingError, JsonCodec } from "./codec.js";
+import { RedisKvStore, RedisKvStoreOptions } from "./kv.js";
+import { RedisMessageQueue, RedisMessageQueueOptions } from "./mq.js";
+export { Codec, CodecError, DecodingError, EncodingError, JsonCodec, RedisKvStore, RedisKvStoreOptions, RedisMessageQueue, RedisMessageQueueOptions };

package/dist/mod.js

@@ -0,0 +1,8 @@
+
+      import { Temporal } from "@js-temporal/polyfill";
+    
+import { CodecError, DecodingError, EncodingError, JsonCodec } from "./codec.js";
+import { RedisKvStore } from "./kv.js";
+import { RedisMessageQueue } from "./mq.js";
+
+export { CodecError, DecodingError, EncodingError, JsonCodec, RedisKvStore, RedisMessageQueue };

package/dist/mq.d.ts

@@ -0,0 +1,76 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { Codec } from "./codec.js";
+import { MessageQueue, MessageQueueEnqueueOptions, MessageQueueListenOptions } from "@fedify/fedify";
+import { Redis, RedisKey } from "ioredis";
+
+//#region mq.d.ts
+/**
+ * Options for {@link RedisMessageQueue} class.
+ */
+interface RedisMessageQueueOptions {
+  /**
+   * The unique identifier for the worker that is processing messages from the
+   * queue.  If this is not specified, a random identifier will be generated.
+   * This is used to prevent multiple workers from processing the same message,
+   * so it should be unique for each worker.
+   */
+  workerId?: string;
+  /**
+   * The Pub/Sub channel key to use for the message queue.  `"fedify_channel"`
+   * by default.
+   * @default `"fedify_channel"`
+   */
+  channelKey?: RedisKey;
+  /**
+   * The Sorted Set key to use for the delayed message queue.  `"fedify_queue"`
+   * by default.
+   * @default `"fedify_queue"`
+   */
+  queueKey?: RedisKey;
+  /**
+   * The key to use for locking the message queue.  `"fedify_lock"` by default.
+   * @default `"fedify_lock"`
+   */
+  lockKey?: RedisKey;
+  /**
+   * The codec to use for encoding and decoding messages in the key-value store.
+   * Defaults to {@link JsonCodec}.
+   * @default {@link JsonCodec}
+   */
+  codec?: Codec;
+  /**
+   * The poll interval for the message queue.  5 seconds by default.
+   * @default `{ seconds: 5 }`
+   */
+  pollInterval?: Temporal.Duration | Temporal.DurationLike;
+}
+/**
+ * A message queue that uses Redis as the underlying storage.
+ *
+ * @example
+ * ```ts ignore
+ * import { createFederation } from "@fedify/fedify";
+ * import { RedisMessageQueue } from "@fedify/redis";
+ * import { Redis } from "ioredis";
+ *
+ * const federation = createFederation({
+ *   // ...
+ *   queue: new RedisMessageQueue(() => new Redis()),
+ * });
+ * ```
+ */
+declare class RedisMessageQueue implements MessageQueue, Disposable {
+  #private;
+  /**
+   * Creates a new Redis message queue.
+   * @param redis The Redis client factory.
+   * @param options The options for the message queue.
+   */
+  constructor(redis: () => Redis, options?: RedisMessageQueueOptions);
+  enqueue(message: any, options?: MessageQueueEnqueueOptions): Promise<void>;
+  enqueueMany(messages: any[], options?: MessageQueueEnqueueOptions): Promise<void>;
+  listen(handler: (message: any) => void | Promise<void>, options?: MessageQueueListenOptions): Promise<void>;
+  [Symbol.dispose](): void;
+}
+//#endregion
+export { RedisMessageQueue, RedisMessageQueueOptions };

package/dist/mq.js

@@ -0,0 +1,144 @@
+
+      import { Temporal } from "@js-temporal/polyfill";
+    
+import { JsonCodec } from "./codec.js";
+import { getLogger } from "@logtape/logtape";
+
+//#region mq.ts
+const logger = getLogger([
+	"fedify",
+	"redis",
+	"mq"
+]);
+/**
+* A message queue that uses Redis as the underlying storage.
+*
+* @example
+* ```ts ignore
+* import { createFederation } from "@fedify/fedify";
+* import { RedisMessageQueue } from "@fedify/redis";
+* import { Redis } from "ioredis";
+*
+* const federation = createFederation({
+*   // ...
+*   queue: new RedisMessageQueue(() => new Redis()),
+* });
+* ```
+*/
+var RedisMessageQueue = class {
+	#redis;
+	#subRedis;
+	#workerId;
+	#channelKey;
+	#queueKey;
+	#lockKey;
+	#codec;
+	#pollIntervalMs;
+	#loopHandle;
+	/**
+	* Creates a new Redis message queue.
+	* @param redis The Redis client factory.
+	* @param options The options for the message queue.
+	*/
+	constructor(redis, options = {}) {
+		this.#redis = redis();
+		this.#subRedis = redis();
+		this.#workerId = options.workerId ?? crypto.randomUUID();
+		this.#channelKey = options.channelKey ?? "fedify_channel";
+		this.#queueKey = options.queueKey ?? "fedify_queue";
+		this.#lockKey = options.lockKey ?? "fedify_lock";
+		this.#codec = options.codec ?? new JsonCodec();
+		this.#pollIntervalMs = Temporal.Duration.from(options.pollInterval ?? { seconds: 5 }).total("millisecond");
+	}
+	async enqueue(message, options) {
+		const ts = options?.delay == null ? 0 : Temporal.Now.instant().add(options.delay).epochMilliseconds;
+		const encodedMessage = this.#codec.encode([crypto.randomUUID(), message]);
+		await this.#redis.zadd(this.#queueKey, ts, encodedMessage);
+		if (ts < 1) this.#redis.publish(this.#channelKey, "");
+	}
+	async enqueueMany(messages, options) {
+		if (messages.length === 0) return;
+		const ts = options?.delay == null ? 0 : Temporal.Now.instant().add(options.delay).epochMilliseconds;
+		const multi = this.#redis.multi();
+		for (const message of messages) {
+			const encodedMessage = this.#codec.encode([crypto.randomUUID(), message]);
+			multi.zadd(this.#queueKey, ts, encodedMessage);
+		}
+		await multi.exec();
+		if (ts < 1) this.#redis.publish(this.#channelKey, "");
+	}
+	async #poll() {
+		logger.debug("Polling for messages...");
+		const result = await this.#redis.set(this.#lockKey, this.#workerId, "EX", Math.floor(this.#pollIntervalMs / 1e3 * 2), "NX");
+		if (result == null) {
+			logger.debug("Another worker is already processing messages; skipping...");
+			return;
+		}
+		logger.debug("Acquired lock; processing messages...");
+		const messages = await this.#redis.zrangebyscoreBuffer(this.#queueKey, 0, Temporal.Now.instant().epochMilliseconds);
+		logger.debug("Found {messages} messages to process.", { messages: messages.length });
+		try {
+			if (messages.length < 1) return;
+			const encodedMessage = messages[0];
+			await this.#redis.zrem(this.#queueKey, encodedMessage);
+			const [_, message] = this.#codec.decode(encodedMessage);
+			return message;
+		} finally {
+			await this.#redis.del(this.#lockKey);
+		}
+	}
+	async listen(handler, options = {}) {
+		if (this.#loopHandle != null) throw new Error("Already listening");
+		const signal = options.signal;
+		const poll = async () => {
+			while (!signal?.aborted) {
+				let message;
+				try {
+					message = await this.#poll();
+				} catch (error) {
+					logger.error("Error polling for messages: {error}", { error });
+					return;
+				}
+				if (message === void 0) return;
+				await handler(message);
+			}
+		};
+		const promise = this.#subRedis.subscribe(this.#channelKey, () => {
+			this.#subRedis.on("message", poll);
+			signal?.addEventListener("abort", () => {
+				this.#subRedis.off("message", poll);
+			});
+		});
+		signal?.addEventListener("abort", () => {
+			for (const timeout of timeouts) clearTimeout(timeout);
+		});
+		const timeouts = /* @__PURE__ */ new Set();
+		while (!signal?.aborted) {
+			let timeout;
+			await new Promise((resolve) => {
+				signal?.addEventListener("abort", resolve);
+				timeout = setTimeout(() => {
+					signal?.removeEventListener("abort", resolve);
+					resolve(0);
+				}, this.#pollIntervalMs);
+				timeouts.add(timeout);
+			});
+			if (timeout != null) timeouts.delete(timeout);
+			await poll();
+		}
+		return await new Promise((resolve) => {
+			signal?.addEventListener("abort", () => {
+				promise.catch(() => resolve()).then(() => resolve());
+			});
+			promise.catch(() => resolve()).then(() => resolve());
+		});
+	}
+	[Symbol.dispose]() {
+		clearInterval(this.#loopHandle);
+		this.#redis.disconnect();
+		this.#subRedis.disconnect();
+	}
+};
+
+//#endregion
+export { RedisMessageQueue };

package/package.json

@@ -1,73 +1,75 @@
 {
   "name": "@fedify/redis",
-  "version": "0.4.0",
+  "version": "1.8.0-pr.278.944+76bf32a2",
   "description": "Redis drivers for Fedify",
   "keywords": [
     "fedify",
     "redis"
   ],
+  "license": "MIT",
   "author": {
     "name": "Hong Minhee",
     "email": "hong@minhee.org",
     "url": "https://hongminhee.org/"
   },
-  "homepage": "https://github.com/fedify-dev/redis",
+  "homepage": "https://fedify.dev/",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/fedify-dev/redis.git"
+    "url": "git+https://github.com/fedify-dev/fedify.git",
+    "directory": "redis"
   },
-  "license": "MIT",
   "bugs": {
-    "url": "https://github.com/fedify-dev/redis/issues"
+    "url": "https://github.com/fedify-dev/fedify/issues"
   },
-  "main": "./script/mod.js",
-  "module": "./esm/mod.js",
-  "types": "./types/mod.d.ts",
+  "funding": [
+    "https://opencollective.com/fedify",
+    "https://github.com/sponsors/dahlia"
+  ],
+  "type": "module",
+  "main": "./dist/mod.js",
+  "module": "./dist/mod.js",
+  "types": "./dist/mod.d.ts",
   "exports": {
     ".": {
-      "import": {
-        "types": "./types/mod.d.ts",
-        "default": "./esm/mod.js"
-      },
-      "require": {
-        "types": "./types/mod.d.ts",
-        "default": "./script/mod.js"
-      }
+      "types": "./dist/mod.d.ts",
+      "import": "./dist/mod.js"
+    },
+    "./codec": {
+      "types": "./dist/codec.d.ts",
+      "import": "./dist/codec.js"
     },
     "./kv": {
-      "import": {
-        "types": "./types/src/kv.d.ts",
-        "default": "./esm/src/kv.js"
-      },
-      "require": {
-        "types": "./types/src/kv.d.ts",
-        "default": "./script/src/kv.js"
-      }
+      "types": "./dist/kv.d.ts",
+      "import": "./dist/kv.js"
     },
     "./mq": {
-      "import": {
-        "types": "./types/src/mq.d.ts",
-        "default": "./esm/src/mq.js"
-      },
-      "require": {
-        "types": "./types/src/mq.d.ts",
-        "default": "./script/src/mq.js"
-      }
-    }
+      "types": "./dist/mq.d.ts",
+      "import": "./dist/mq.js"
+    },
+    "./package.json": "./package.json"
   },
-  "funding": [
-    "https://opencollective.com/fedify",
-    "https://github.com/sponsors/dahlia"
+  "files": [
+    "dist",
+    "package.json"
   ],
   "dependencies": {
-    "@fedify/fedify": "1.5.0",
-    "@logtape/logtape": "^0.9.0",
-    "ioredis": "^5.4.1",
-    "@deno/shim-deno": "~0.18.0",
-    "@js-temporal/polyfill": "^0.5.0"
+    "@js-temporal/polyfill": "^0.5.1",
+    "@logtape/logtape": "^1.0.0"
+  },
+  "peerDependencies": {
+    "ioredis": "^5.6.1",
+    "@fedify/fedify": "1.8.0-pr.278.944+76bf32a2"
   },
   "devDependencies": {
-    "@types/node": "^20.9.0"
+    "@std/async": "npm:@jsr/std__async@^1.0.13",
+    "@types/node": "^22.16.0",
+    "tsdown": "^0.12.9",
+    "typescript": "^5.8.3"
   },
-  "_generatedBy": "dnt@dev"
+  "scripts": {
+    "build": "tsdown",
+    "prepublish": "tsdown",
+    "test": "tsdown && node --experimental-transform-types --test",
+    "test:bun": "tsdown && bun test --timeout=10000"
+  }
 }