@fedify/postgres 0.4.0-dev.31 → 1.8.0-dev.1004

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

@@ -5,7 +5,6 @@
 
 [![JSR][JSR badge]][JSR]
 [![npm][npm badge]][npm]
-[![GitHub Actions][GitHub Actions badge]][GitHub Actions]
 
 This package provides [Fedify]'s [`KvStore`] and [`MessageQueue`]
 implementations for PostgreSQL:
@@ -30,88 +29,20 @@ const federation = createFederation({
 [JSR badge]: https://jsr.io/badges/@fedify/postgres
 [npm]: https://www.npmjs.com/package/@fedify/postgres
 [npm badge]: https://img.shields.io/npm/v/@fedify/postgres?logo=npm
-[GitHub Actions]: https://github.com/fedify-dev/postgres/actions/workflows/main.yaml
-[GitHub Actions badge]: https://github.com/fedify-dev/postgres/actions/workflows/main.yaml/badge.svg
 [Fedify]: https://fedify.dev/
 [`KvStore`]: https://jsr.io/@fedify/fedify/doc/federation/~/KvStore
 [`MessageQueue`]: https://jsr.io/@fedify/fedify/doc/federation/~/MessageQueue
-[`PostgresKvStore`]: https://jsr.io/@fedify/postgres/doc/federation/~/PostgresKvStore
-[`PostgresMessageQueue`]: https://jsr.io/@fedify/postgres/doc/federation/~/PostgresMessageQueue
+[`PostgresKvStore`]: https://jsr.io/@fedify/postgres/doc/~/PostgresKvStore
+[`PostgresMessageQueue`]: https://jsr.io/@fedify/postgres/doc/~/PostgresMessageQueue
 
 
 Installation
 ------------
 
-### Deno
-
-~~~~ sh
-deno add @fedify/postgres
-~~~~
-
-### Node.js
-
-~~~~ sh
-npm install @fedify/postgres
-~~~~
-
-### Bun
-
 ~~~~ sh
-bun add @fedify/postgres
+deno add jsr:@fedify/postgres  # Deno
+npm  add     @fedify/postgres  # npm
+pnpm add     @fedify/postgres  # pnpm
+yarn add     @fedify/postgres  # Yarn
+bun  add     @fedify/postgres  # Bun
 ~~~~
-
-
-Changelog
----------
-
-### Version 0.4.0
-
-To be released.
-
-### Version 0.3.0
-
-Released on March 28, 2025.
-
- -  Added `PostgresMessageQueue.enqueueMany()` method for efficiently enqueuing
-    multiple messages at once.
-
- -  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.
-
- -  Added some logging using [LogTape] for the sake of debugging.  The following
-    categories are used:
-
-     -  `["fedify", "postgres", "kv"]`
-     -  `["fedify", "postgres", "mq"]`
-
-[LogTape]: https://logtape.org/
-
-### Version 0.2.2
-
-Released on November 18, 2024.
-
- -  Fixed a bug where binding parameters have not been properly escaped with
-    some settings of Postgres.js.
-
-### Version 0.2.1
-
-Released on November 3, 2024.
-
- -  Fixed a bug where some scalar values have failed to be stored in the
-    database.
-
-### Version 0.2.0
-
-Released on November 3, 2024.
-
- -  Fixed a bug where JSON values are double-quoted in the database.  Since it's
-    a breaking change data-wise, the default values of the following options
-    are also changed:
-
-     -  `PostgresKvStoreOptions.tableName` defaults to `"fedify_kv_v2"`.
-     -  `PostgresMessageQueueOptions.tableName` defaults to
-        `"fedify_message_v2"`.
-
-### Version 0.1.0
-
-Initial release.  Released on September 26, 2024.

package/deno.json

@@ -1,34 +1,22 @@
 {
   "name": "@fedify/postgres",
-  "version": "0.4.0-dev.31+c73d0d82",
+  "version": "1.8.0-dev.1004+d5b05e27",
   "license": "MIT",
   "exports": {
     ".": "./mod.ts",
-    "./kv": "./src/kv.ts",
-    "./mq": "./src/mq.ts"
-  },
-  "imports": {
-    "@deno/dnt": "jsr:@deno/dnt@^0.41.3",
-    "@fedify/fedify": "jsr:@fedify/fedify@1.7.2",
-    "@logtape/logtape": "jsr:@logtape/logtape@^1.0.0",
-    "@std/assert": "jsr:@std/assert@^1.0.4",
-    "@std/async": "jsr:@std/async@^1.0.5",
-    "postgres": "npm:postgres@^3.4.7",
-    "tsdown": "npm:tsdown@^0.12.9"
+    "./kv": "./kv.ts",
+    "./mq": "./mq.ts"
   },
   "nodeModulesDir": "none",
   "unstable": [
     "temporal"
   ],
   "exclude": [
-    ".github",
-    ".test-report.xml",
-    "npm",
-    "pnpm-lock.yaml"
+    "dist",
+    "node_modules"
   ],
   "tasks": {
-    "check": "deno fmt --check && deno lint && deno check */*.ts",
-    "test": "deno test --allow-net --allow-env",
-    "dnt": "deno run -A dnt.ts"
+    "check": "deno fmt --check && deno lint && deno check *.ts",
+    "test": "deno test --allow-net --allow-env"
   }
 }

package/dist/kv.d.ts

@@ -0,0 +1,60 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { Sql } from "postgres";
+import { KvKey, KvStore, KvStoreSetOptions } from "@fedify/fedify";
+
+//#region kv.d.ts
+/**
+ * Options for the PostgreSQL key-value store.
+ */
+interface PostgresKvStoreOptions {
+  /**
+   * The table name to use for the key-value store.
+   * `"fedify_kv_v2"` by default.
+   * @default `"fedify_kv_v2"`
+   */
+  tableName?: string;
+  /**
+   * Whether the table has been initialized.  `false` by default.
+   * @default `false`
+   */
+  initialized?: boolean;
+}
+/**
+ * A key-value store that uses PostgreSQL as the underlying storage.
+ *
+ * @example
+ * ```ts
+ * import { createFederation } from "@fedify/fedify";
+ * import { PostgresKvStore } from "@fedify/postgres";
+ * import postgres from "postgres";
+ *
+ * const federation = createFederation({
+ *   // ...
+ *   kv: new PostgresKvStore(postgres("postgres://user:pass@localhost/db")),
+ * });
+ * ```
+ */
+declare class PostgresKvStore implements KvStore {
+  #private;
+  /**
+   * Creates a new PostgreSQL key-value store.
+   * @param sql The PostgreSQL client to use.
+   * @param options The options for the key-value store.
+   */
+  constructor(sql: Sql<{}>, options?: PostgresKvStoreOptions);
+  get<T = unknown>(key: KvKey): Promise<T | undefined>;
+  set(key: KvKey, value: unknown, options?: KvStoreSetOptions | undefined): Promise<void>;
+  delete(key: KvKey): Promise<void>;
+  /**
+   * Creates the table used by the key-value store if it does not already exist.
+   * Does nothing if the table already exists.
+   */
+  initialize(): Promise<void>;
+  /**
+   * Drops the table used by the key-value store.  Does nothing if the table
+   * does not exist.
+   */
+  drop(): Promise<void>;
+}
+//#endregion
+export { PostgresKvStore, PostgresKvStoreOptions };

package/dist/kv.js

@@ -0,0 +1,115 @@
+
+      import { Temporal } from "@js-temporal/polyfill";
+    
+import { driverSerializesJson } from "./utils.js";
+import { getLogger } from "@logtape/logtape";
+
+//#region kv.ts
+const logger = getLogger([
+	"fedify",
+	"postgres",
+	"kv"
+]);
+/**
+* A key-value store that uses PostgreSQL as the underlying storage.
+*
+* @example
+* ```ts
+* import { createFederation } from "@fedify/fedify";
+* import { PostgresKvStore } from "@fedify/postgres";
+* import postgres from "postgres";
+*
+* const federation = createFederation({
+*   // ...
+*   kv: new PostgresKvStore(postgres("postgres://user:pass@localhost/db")),
+* });
+* ```
+*/
+var PostgresKvStore = class {
+	#sql;
+	#tableName;
+	#initialized;
+	#driverSerializesJson = false;
+	/**
+	* Creates a new PostgreSQL key-value store.
+	* @param sql The PostgreSQL client to use.
+	* @param options The options for the key-value store.
+	*/
+	constructor(sql, options = {}) {
+		this.#sql = sql;
+		this.#tableName = options.tableName ?? "fedify_kv_v2";
+		this.#initialized = options.initialized ?? false;
+	}
+	async #expire() {
+		await this.#sql`
+      DELETE FROM ${this.#sql(this.#tableName)}
+      WHERE ttl IS NOT NULL AND created + ttl < CURRENT_TIMESTAMP;
+    `;
+	}
+	async get(key) {
+		await this.initialize();
+		const result = await this.#sql`
+      SELECT value
+      FROM ${this.#sql(this.#tableName)}
+      WHERE key = ${key} AND (ttl IS NULL OR created + ttl > CURRENT_TIMESTAMP);
+    `;
+		if (result.length < 1) return void 0;
+		return result[0].value;
+	}
+	async set(key, value, options) {
+		await this.initialize();
+		const ttl = options?.ttl == null ? null : options.ttl.toString();
+		await this.#sql`
+      INSERT INTO ${this.#sql(this.#tableName)} (key, value, ttl)
+      VALUES (
+        ${key},
+        ${this.#json(value)},
+        ${ttl}
+      )
+      ON CONFLICT (key)
+        DO UPDATE SET value = EXCLUDED.value, ttl = EXCLUDED.ttl;
+    `;
+		await this.#expire();
+	}
+	async delete(key) {
+		await this.initialize();
+		await this.#sql`
+      DELETE FROM ${this.#sql(this.#tableName)}
+      WHERE key = ${key};
+    `;
+		await this.#expire();
+	}
+	/**
+	* Creates the table used by the key-value store if it does not already exist.
+	* Does nothing if the table already exists.
+	*/
+	async initialize() {
+		if (this.#initialized) return;
+		logger.debug("Initializing the key-value store table {tableName}...", { tableName: this.#tableName });
+		await this.#sql`
+      CREATE UNLOGGED TABLE IF NOT EXISTS ${this.#sql(this.#tableName)} (
+        key text[] PRIMARY KEY,
+        value jsonb NOT NULL,
+        created timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
+        ttl interval
+      );
+    `;
+		this.#driverSerializesJson = await driverSerializesJson(this.#sql);
+		this.#initialized = true;
+		logger.debug("Initialized the key-value store table {tableName}.", { tableName: this.#tableName });
+	}
+	/**
+	* Drops the table used by the key-value store.  Does nothing if the table
+	* does not exist.
+	*/
+	async drop() {
+		await this.#sql`DROP TABLE IF EXISTS ${this.#sql(this.#tableName)};`;
+	}
+	#json(value) {
+		if (this.#driverSerializesJson) return this.#sql.json(value);
+		return this.#sql.json(JSON.stringify(value));
+	}
+};
+
+//#endregion
+export { PostgresKvStore };

package/dist/mod.d.ts

@@ -0,0 +1,4 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { PostgresKvStore, PostgresKvStoreOptions } from "./kv.js";
+import { PostgresMessageQueue, PostgresMessageQueueOptions } from "./mq.js";
+export { PostgresKvStore, PostgresKvStoreOptions, PostgresMessageQueue, PostgresMessageQueueOptions };

package/dist/mod.js

@@ -0,0 +1,7 @@
+
+      import { Temporal } from "@js-temporal/polyfill";
+    
+import { PostgresKvStore } from "./kv.js";
+import { PostgresMessageQueue } from "./mq.js";
+
+export { PostgresKvStore, PostgresMessageQueue };

package/dist/mq.d.ts

@@ -0,0 +1,66 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { Sql } from "postgres";
+import { MessageQueue, MessageQueueEnqueueOptions, MessageQueueListenOptions } from "@fedify/fedify";
+
+//#region mq.d.ts
+/**
+ * Options for the PostgreSQL message queue.
+ */
+interface PostgresMessageQueueOptions {
+  /**
+   * The table name to use for the message queue.
+   * `"fedify_message_v2"` by default.
+   * @default `"fedify_message_v2"`
+   */
+  tableName?: string;
+  /**
+   * The channel name to use for the message queue.
+   * `"fedify_channel"` by default.
+   * @default `"fedify_channel"`
+   */
+  channelName?: string;
+  /**
+   * Whether the table has been initialized.  `false` by default.
+   * @default `false`
+   */
+  initialized?: boolean;
+  /**
+   * The poll interval for the message queue.  5 seconds by default.
+   * @default `{ seconds: 5 }`
+   */
+  pollInterval?: Temporal.Duration | Temporal.DurationLike;
+}
+/**
+ * A message queue that uses PostgreSQL as the underlying storage.
+ *
+ * @example
+ * ```ts
+ * import { createFederation } from "@fedify/fedify";
+ * import { PostgresKvStore, PostgresMessageQueue } from "@fedify/postgres";
+ * import postgres from "postgres";
+ *
+ * const sql = postgres("postgres://user:pass@localhost/db");
+ *
+ * const federation = createFederation({
+ *   kv: new PostgresKvStore(sql),
+ *   queue: new PostgresMessageQueue(sql),
+ * });
+ * ```
+ */
+declare class PostgresMessageQueue implements MessageQueue {
+  #private;
+  constructor(sql: Sql<{}>, options?: PostgresMessageQueueOptions);
+  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>;
+  /**
+   * Initializes the message queue table if it does not already exist.
+   */
+  initialize(): Promise<void>;
+  /**
+   * Drops the message queue table if it exists.
+   */
+  drop(): Promise<void>;
+}
+//#endregion
+export { PostgresMessageQueue, PostgresMessageQueueOptions };

package/dist/mq.js

@@ -0,0 +1,185 @@
+
+      import { Temporal } from "@js-temporal/polyfill";
+    
+import { driverSerializesJson } from "./utils.js";
+import { getLogger } from "@logtape/logtape";
+import postgres from "postgres";
+
+//#region mq.ts
+const logger = getLogger([
+	"fedify",
+	"postgres",
+	"mq"
+]);
+/**
+* A message queue that uses PostgreSQL as the underlying storage.
+*
+* @example
+* ```ts
+* import { createFederation } from "@fedify/fedify";
+* import { PostgresKvStore, PostgresMessageQueue } from "@fedify/postgres";
+* import postgres from "postgres";
+*
+* const sql = postgres("postgres://user:pass@localhost/db");
+*
+* const federation = createFederation({
+*   kv: new PostgresKvStore(sql),
+*   queue: new PostgresMessageQueue(sql),
+* });
+* ```
+*/
+var PostgresMessageQueue = class {
+	#sql;
+	#tableName;
+	#channelName;
+	#pollIntervalMs;
+	#initialized;
+	#driverSerializesJson = false;
+	constructor(sql, options = {}) {
+		this.#sql = sql;
+		this.#tableName = options?.tableName ?? "fedify_message_v2";
+		this.#channelName = options?.channelName ?? "fedify_channel";
+		this.#pollIntervalMs = Temporal.Duration.from(options?.pollInterval ?? { seconds: 5 }).total("millisecond");
+		this.#initialized = options?.initialized ?? false;
+	}
+	async enqueue(message, options) {
+		await this.initialize();
+		const delay = options?.delay ?? Temporal.Duration.from({ seconds: 0 });
+		if (options?.delay) logger.debug("Enqueuing a message with a delay of {delay}...", {
+			delay,
+			message
+		});
+		else logger.debug("Enqueuing a message...", { message });
+		await this.#sql`
+      INSERT INTO ${this.#sql(this.#tableName)} (message, delay)
+      VALUES (
+        ${this.#json(message)},
+        ${delay.toString()}
+      );
+    `;
+		logger.debug("Enqueued a message.", { message });
+		await this.#sql.notify(this.#channelName, delay.toString());
+		logger.debug("Notified the message queue channel {channelName}.", {
+			channelName: this.#channelName,
+			message
+		});
+	}
+	async enqueueMany(messages, options) {
+		if (messages.length === 0) return;
+		await this.initialize();
+		const delay = options?.delay ?? Temporal.Duration.from({ seconds: 0 });
+		if (options?.delay) logger.debug("Enqueuing messages with a delay of {delay}...", {
+			delay,
+			messages
+		});
+		else logger.debug("Enqueuing messages...", { messages });
+		for (const message of messages) await this.#sql`
+        INSERT INTO ${this.#sql(this.#tableName)} (message, delay)
+        VALUES (
+          ${this.#json(message)},
+          ${delay.toString()}
+        );
+      `;
+		logger.debug("Enqueued messages.", { messages });
+		await this.#sql.notify(this.#channelName, delay.toString());
+		logger.debug("Notified the message queue channel {channelName}.", {
+			channelName: this.#channelName,
+			messages
+		});
+	}
+	async listen(handler, options = {}) {
+		await this.initialize();
+		const { signal } = options;
+		const poll = async () => {
+			while (!signal?.aborted) {
+				const query = this.#sql`
+          DELETE FROM ${this.#sql(this.#tableName)}
+          WHERE id = (
+            SELECT id
+            FROM ${this.#sql(this.#tableName)}
+            WHERE created + delay < CURRENT_TIMESTAMP
+            ORDER BY created
+            LIMIT 1
+          )
+          RETURNING message;
+        `.execute();
+				const cancel = query.cancel.bind(query);
+				signal?.addEventListener("abort", cancel);
+				let i = 0;
+				for (const message of await query) {
+					if (signal?.aborted) return;
+					await handler(message.message);
+					i++;
+				}
+				signal?.removeEventListener("abort", cancel);
+				if (i < 1) break;
+			}
+		};
+		const timeouts = /* @__PURE__ */ new Set();
+		const listen = await this.#sql.listen(this.#channelName, async (delay) => {
+			const duration = Temporal.Duration.from(delay);
+			const durationMs = duration.total("millisecond");
+			if (durationMs < 1) await poll();
+			else timeouts.add(setTimeout(poll, durationMs));
+		}, poll);
+		signal?.addEventListener("abort", () => {
+			listen.unlisten();
+			for (const timeout of timeouts) clearTimeout(timeout);
+		});
+		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();
+		}
+		await new Promise((resolve) => {
+			signal?.addEventListener("abort", () => resolve());
+			if (signal?.aborted) return resolve();
+		});
+	}
+	/**
+	* Initializes the message queue table if it does not already exist.
+	*/
+	async initialize() {
+		if (this.#initialized) return;
+		logger.debug("Initializing the message queue table {tableName}...", { tableName: this.#tableName });
+		try {
+			await this.#sql`
+      CREATE TABLE IF NOT EXISTS ${this.#sql(this.#tableName)} (
+        id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+        message jsonb NOT NULL,
+        delay interval DEFAULT '0 seconds',
+        created timestamp with time zone DEFAULT CURRENT_TIMESTAMP
+      );
+    `;
+		} catch (error) {
+			if (!(error instanceof postgres.PostgresError && error.constraint_name === "pg_type_typname_nsp_index")) {
+				logger.error("Failed to initialize the message queue table: {error}", { error });
+				throw error;
+			}
+		}
+		this.#driverSerializesJson = await driverSerializesJson(this.#sql);
+		this.#initialized = true;
+		logger.debug("Initialized the message queue table {tableName}.", { tableName: this.#tableName });
+	}
+	/**
+	* Drops the message queue table if it exists.
+	*/
+	async drop() {
+		await this.#sql`DROP TABLE IF EXISTS ${this.#sql(this.#tableName)};`;
+	}
+	#json(value) {
+		if (this.#driverSerializesJson) return this.#sql.json(value);
+		return this.#sql.json(JSON.stringify(value));
+	}
+};
+
+//#endregion
+export { PostgresMessageQueue };

package/dist/utils.js

@@ -0,0 +1,11 @@
+
+      import { Temporal } from "@js-temporal/polyfill";
+    
+//#region utils.ts
+async function driverSerializesJson(sql) {
+	const result = await sql`SELECT ${sql.json("{\"foo\":1}")}::jsonb AS test;`;
+	return result[0].test === "{\"foo\":1}";
+}
+
+//#endregion
+export { driverSerializesJson };

package/{src/kv.test.ts → kv.test.ts}

@@ -31,6 +31,7 @@ function getStore(): {
 }
 
 test("PostgresKvStore.initialize()", { skip: dbUrl == null }, async () => {
+  if (dbUrl == null) return; // Bun does not support skip option
   const { sql, tableName, store } = getStore();
   try {
     await store.initialize();
@@ -45,6 +46,7 @@ test("PostgresKvStore.initialize()", { skip: dbUrl == null }, async () => {
 });
 
 test("PostgresKvStore.get()", { skip: dbUrl == null }, async () => {
+  if (dbUrl == null) return; // Bun does not support skip option
   const { sql, tableName, store } = getStore();
   try {
     await store.initialize();
@@ -67,6 +69,7 @@ test("PostgresKvStore.get()", { skip: dbUrl == null }, async () => {
 });
 
 test("PostgresKvStore.set()", { skip: dbUrl == null }, async () => {
+  if (dbUrl == null) return; // Bun does not support skip option
   const { sql, tableName, store } = getStore();
   try {
     await store.set(["foo", "baz"], "baz");
@@ -107,6 +110,7 @@ test("PostgresKvStore.set()", { skip: dbUrl == null }, async () => {
 });
 
 test("PostgresKvStore.delete()", { skip: dbUrl == null }, async () => {
+  if (dbUrl == null) return; // Bun does not support skip option
   const { sql, tableName, store } = getStore();
   try {
     await store.delete(["foo", "bar"]);
@@ -122,6 +126,7 @@ test("PostgresKvStore.delete()", { skip: dbUrl == null }, async () => {
 });
 
 test("PostgresKvStore.drop()", { skip: dbUrl == null }, async () => {
+  if (dbUrl == null) return; // Bun does not support skip option
   const { sql, tableName, store } = getStore();
   try {
     await store.drop();

package/mod.ts

@@ -1 +1,2 @@
-export * from "./src/mod.ts";
+export * from "./kv.ts";
+export * from "./mq.ts";

package/{src/mq.test.ts → mq.test.ts}

@@ -16,6 +16,7 @@ if ("Temporal" in globalThis) {
 const dbUrl = process.env.DATABASE_URL;
 
 test("PostgresMessageQueue", { skip: dbUrl == null }, async () => {
+  if (dbUrl == null) return; // Bun does not support skip option
   const sql = postgres(dbUrl!);
   const sql2 = postgres(dbUrl!);
   const tableName = `fedify_message_test_${

package/{src/mq.ts → mq.ts}

@@ -47,14 +47,14 @@ export interface PostgresMessageQueueOptions {
  * @example
  * ```ts
  * import { createFederation } from "@fedify/fedify";
- * import { PostgresMessageQueue } from "@fedify/postgres";
+ * import { PostgresKvStore, PostgresMessageQueue } from "@fedify/postgres";
  * import postgres from "postgres";
  *
+ * const sql = postgres("postgres://user:pass@localhost/db");
+ *
  * const federation = createFederation({
- *   // ...
- *   queue: new PostgresMessageQueue(
- *     postgres("postgres://user:pass@localhost/db")
- *   ),
+ *   kv: new PostgresKvStore(sql),
+ *   queue: new PostgresMessageQueue(sql),
  * });
  * ```
  */