@fedify/postgres 2.0.0-pr.490.2 → 2.0.0-pr.559.4

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright 2024–2025 Hong Minhee
+Copyright 2024–2026 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

@@ -25,10 +25,10 @@ const federation = createFederation({
 });
 ~~~~
 
-[JSR]: https://jsr.io/@fedify/postgres
 [JSR badge]: https://jsr.io/badges/@fedify/postgres
-[npm]: https://www.npmjs.com/package/@fedify/postgres
+[JSR]: https://jsr.io/@fedify/postgres
 [npm badge]: https://img.shields.io/npm/v/@fedify/postgres?logo=npm
+[npm]: https://www.npmjs.com/package/@fedify/postgres
 [Fedify]: https://fedify.dev/
 [`KvStore`]: https://jsr.io/@fedify/fedify/doc/federation/~/KvStore
 [`MessageQueue`]: https://jsr.io/@fedify/fedify/doc/federation/~/MessageQueue

package/dist/kv.cjs

@@ -81,6 +81,35 @@ var PostgresKvStore = class {
 		await this.#expire();
 	}
 	/**
+	* {@inheritDoc KvStore.list}
+	* @since 1.10.0
+	*/
+	async *list(prefix) {
+		await this.initialize();
+		let results;
+		if (prefix == null || prefix.length === 0) results = await this.#sql`
+        SELECT key, value
+        FROM ${this.#sql(this.#tableName)}
+        WHERE ttl IS NULL OR created + ttl > CURRENT_TIMESTAMP
+        ORDER BY key
+      `;
+		else {
+			const prefixLength = prefix.length;
+			results = await this.#sql`
+        SELECT key, value
+        FROM ${this.#sql(this.#tableName)}
+        WHERE array_length(key, 1) >= ${prefixLength}
+          AND key[1:${prefixLength}] = ${prefix}::text[]
+          AND (ttl IS NULL OR created + ttl > CURRENT_TIMESTAMP)
+        ORDER BY key
+      `;
+		}
+		for (const row of results) yield {
+			key: row.key,
+			value: row.value
+		};
+	}
+	/**
 	* Creates the table used by the key–value store if it does not already exist.
 	* Does nothing if the table already exists.
 	*/

package/dist/kv.d.cts

@@ -1,4 +1,4 @@
-import { KvKey, KvStore, KvStoreSetOptions } from "@fedify/fedify";
+import { KvKey, KvStore, KvStoreListEntry, KvStoreSetOptions } from "@fedify/fedify";
 import { Sql } from "postgres";
 
 //#region src/kv.d.ts
@@ -11,12 +11,12 @@ interface PostgresKvStoreOptions {
    * `"fedify_kv_v2"` by default.
    * @default `"fedify_kv_v2"`
    */
-  tableName?: string;
+  readonly tableName?: string;
   /**
    * Whether the table has been initialized.  `false` by default.
    * @default `false`
    */
-  initialized?: boolean;
+  readonly initialized?: boolean;
 }
 /**
  * A key–value store that uses PostgreSQL as the underlying storage.
@@ -44,6 +44,11 @@ declare class PostgresKvStore implements KvStore {
   get<T = unknown>(key: KvKey): Promise<T | undefined>;
   set(key: KvKey, value: unknown, options?: KvStoreSetOptions | undefined): Promise<void>;
   delete(key: KvKey): Promise<void>;
+  /**
+   * {@inheritDoc KvStore.list}
+   * @since 1.10.0
+   */
+  list(prefix?: KvKey): AsyncIterable<KvStoreListEntry>;
   /**
    * Creates the table used by the key–value store if it does not already exist.
    * Does nothing if the table already exists.

package/dist/kv.d.ts

@@ -1,6 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { Sql } from "postgres";
-import { KvKey, KvStore, KvStoreSetOptions } from "@fedify/fedify";
+import { KvKey, KvStore, KvStoreListEntry, KvStoreSetOptions } from "@fedify/fedify";
 
 //#region src/kv.d.ts
 /**
@@ -12,12 +12,12 @@ interface PostgresKvStoreOptions {
    * `"fedify_kv_v2"` by default.
    * @default `"fedify_kv_v2"`
    */
-  tableName?: string;
+  readonly tableName?: string;
   /**
    * Whether the table has been initialized.  `false` by default.
    * @default `false`
    */
-  initialized?: boolean;
+  readonly initialized?: boolean;
 }
 /**
  * A key–value store that uses PostgreSQL as the underlying storage.
@@ -45,6 +45,11 @@ declare class PostgresKvStore implements KvStore {
   get<T = unknown>(key: KvKey): Promise<T | undefined>;
   set(key: KvKey, value: unknown, options?: KvStoreSetOptions | undefined): Promise<void>;
   delete(key: KvKey): Promise<void>;
+  /**
+   * {@inheritDoc KvStore.list}
+   * @since 1.10.0
+   */
+  list(prefix?: KvKey): AsyncIterable<KvStoreListEntry>;
   /**
    * Creates the table used by the key–value store if it does not already exist.
    * Does nothing if the table already exists.

package/dist/kv.js

@@ -80,6 +80,35 @@ var PostgresKvStore = class {
 		await this.#expire();
 	}
 	/**
+	* {@inheritDoc KvStore.list}
+	* @since 1.10.0
+	*/
+	async *list(prefix) {
+		await this.initialize();
+		let results;
+		if (prefix == null || prefix.length === 0) results = await this.#sql`
+        SELECT key, value
+        FROM ${this.#sql(this.#tableName)}
+        WHERE ttl IS NULL OR created + ttl > CURRENT_TIMESTAMP
+        ORDER BY key
+      `;
+		else {
+			const prefixLength = prefix.length;
+			results = await this.#sql`
+        SELECT key, value
+        FROM ${this.#sql(this.#tableName)}
+        WHERE array_length(key, 1) >= ${prefixLength}
+          AND key[1:${prefixLength}] = ${prefix}::text[]
+          AND (ttl IS NULL OR created + ttl > CURRENT_TIMESTAMP)
+        ORDER BY key
+      `;
+		}
+		for (const row of results) yield {
+			key: row.key,
+			value: row.value
+		};
+	}
+	/**
 	* Creates the table used by the key–value store if it does not already exist.
 	* Does nothing if the table already exists.
 	*/

package/dist/mq.cjs

@@ -46,46 +46,66 @@ var PostgresMessageQueue = class {
 	async enqueue(message, options) {
 		await this.initialize();
 		const delay = options?.delay ?? Temporal.Duration.from({ seconds: 0 });
+		const orderingKey = options?.orderingKey ?? null;
 		if (options?.delay) logger.debug("Enqueuing a message with a delay of {delay}...", {
 			delay,
-			message
+			message,
+			orderingKey
+		});
+		else logger.debug("Enqueuing a message...", {
+			message,
+			orderingKey
 		});
-		else logger.debug("Enqueuing a message...", { message });
 		await this.#sql`
-      INSERT INTO ${this.#sql(this.#tableName)} (message, delay)
+      INSERT INTO ${this.#sql(this.#tableName)} (message, delay, ordering_key)
       VALUES (
         ${this.#json(message)},
-        ${delay.toString()}
+        ${delay.toString()},
+        ${orderingKey}
       );
     `;
-		logger.debug("Enqueued a message.", { message });
+		logger.debug("Enqueued a message.", {
+			message,
+			orderingKey
+		});
 		await this.#sql.notify(this.#channelName, delay.toString());
 		logger.debug("Notified the message queue channel {channelName}.", {
 			channelName: this.#channelName,
-			message
+			message,
+			orderingKey
 		});
 	}
 	async enqueueMany(messages, options) {
 		if (messages.length === 0) return;
 		await this.initialize();
 		const delay = options?.delay ?? Temporal.Duration.from({ seconds: 0 });
+		const orderingKey = options?.orderingKey ?? null;
 		if (options?.delay) logger.debug("Enqueuing messages with a delay of {delay}...", {
 			delay,
-			messages
+			messages,
+			orderingKey
+		});
+		else logger.debug("Enqueuing messages...", {
+			messages,
+			orderingKey
 		});
-		else logger.debug("Enqueuing messages...", { messages });
 		for (const message of messages) await this.#sql`
-        INSERT INTO ${this.#sql(this.#tableName)} (message, delay)
+        INSERT INTO ${this.#sql(this.#tableName)} (message, delay, ordering_key)
         VALUES (
           ${this.#json(message)},
-          ${delay.toString()}
+          ${delay.toString()},
+          ${orderingKey}
         );
       `;
-		logger.debug("Enqueued messages.", { messages });
+		logger.debug("Enqueued messages.", {
+			messages,
+			orderingKey
+		});
 		await this.#sql.notify(this.#channelName, delay.toString());
 		logger.debug("Notified the message queue channel {channelName}.", {
 			channelName: this.#channelName,
-			messages
+			messages,
+			orderingKey
 		});
 	}
 	async listen(handler, options = {}) {
@@ -93,27 +113,77 @@ var PostgresMessageQueue = class {
 		const { signal } = options;
 		const poll = async () => {
 			while (!signal?.aborted) {
+				let processed = false;
 				const query = this.#sql`
-          DELETE FROM ${this.#sql(this.#tableName)}
-          WHERE id = (
-            SELECT id
+          WITH candidate AS (
+            SELECT id, ordering_key
             FROM ${this.#sql(this.#tableName)}
             WHERE created + delay < CURRENT_TIMESTAMP
+              AND ordering_key IS NULL
             ORDER BY created
             LIMIT 1
+            FOR UPDATE SKIP LOCKED
           )
-          RETURNING message;
+          DELETE FROM ${this.#sql(this.#tableName)}
+          WHERE id IN (SELECT id FROM candidate)
+          RETURNING message, ordering_key;
         `.execute();
 				const cancel = query.cancel.bind(query);
 				signal?.addEventListener("abort", cancel);
-				let i = 0;
-				for (const message of await query) {
+				for (const row of await query) {
 					if (signal?.aborted) return;
-					await handler(message.message);
-					i++;
+					await handler(row.message);
+					processed = true;
 				}
 				signal?.removeEventListener("abort", cancel);
-				if (i < 1) break;
+				if (processed) continue;
+				const attemptedOrderingKeys = /* @__PURE__ */ new Set();
+				while (!signal?.aborted) {
+					const candidateResult = await this.#sql`
+            SELECT id, ordering_key
+            FROM ${this.#sql(this.#tableName)}
+            WHERE created + delay < CURRENT_TIMESTAMP
+              AND ordering_key IS NOT NULL
+              ${attemptedOrderingKeys.size > 0 ? this.#sql`AND ordering_key NOT IN ${this.#sql([...attemptedOrderingKeys])}` : this.#sql``}
+            ORDER BY created
+            LIMIT 1
+          `;
+					if (candidateResult.length === 0) break;
+					const candidate = candidateResult[0];
+					const candidateId = candidate.id;
+					const orderingKey = candidate.ordering_key;
+					attemptedOrderingKeys.add(orderingKey);
+					const lockResult = await this.#sql`
+            SELECT pg_try_advisory_lock(
+              hashtext(${this.#tableName}),
+              hashtext(${orderingKey})
+            ) AS acquired
+          `;
+					if (lockResult[0].acquired) {
+						try {
+							const deleteResult = await this.#sql`
+                DELETE FROM ${this.#sql(this.#tableName)}
+                WHERE id = ${candidateId}
+                RETURNING message, ordering_key
+              `;
+							for (const row of deleteResult) {
+								if (signal?.aborted) return;
+								await handler(row.message);
+								processed = true;
+							}
+						} finally {
+							await this.#sql`
+                SELECT pg_advisory_unlock(
+                  hashtext(${this.#tableName}),
+                  hashtext(${orderingKey})
+                )
+              `;
+						}
+						if (processed) break;
+					}
+				}
+				if (processed) continue;
+				break;
 			}
 		};
 		const timeouts = /* @__PURE__ */ new Set();
@@ -157,8 +227,13 @@ var PostgresMessageQueue = class {
         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
+        created timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
+        ordering_key text
       );
+    `;
+			await this.#sql`
+      ALTER TABLE ${this.#sql(this.#tableName)}
+      ADD COLUMN IF NOT EXISTS ordering_key text;
     `;
 		} catch (error) {
 			if (!(error instanceof postgres.default.PostgresError && error.constraint_name === "pg_type_typname_nsp_index")) {

package/dist/mq.d.cts

@@ -11,23 +11,23 @@ interface PostgresMessageQueueOptions {
    * `"fedify_message_v2"` by default.
    * @default `"fedify_message_v2"`
    */
-  tableName?: string;
+  readonly tableName?: string;
   /**
    * The channel name to use for the message queue.
    * `"fedify_channel"` by default.
    * @default `"fedify_channel"`
    */
-  channelName?: string;
+  readonly channelName?: string;
   /**
    * Whether the table has been initialized.  `false` by default.
    * @default `false`
    */
-  initialized?: boolean;
+  readonly initialized?: boolean;
   /**
    * The poll interval for the message queue.  5 seconds by default.
    * @default `{ seconds: 5 }`
    */
-  pollInterval?: Temporal.Duration | Temporal.DurationLike;
+  readonly pollInterval?: Temporal.Duration | Temporal.DurationLike;
 }
 /**
  * A message queue that uses PostgreSQL as the underlying storage.
@@ -50,7 +50,7 @@ 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>;
+  enqueueMany(messages: readonly 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.

package/dist/mq.d.ts

@@ -12,23 +12,23 @@ interface PostgresMessageQueueOptions {
    * `"fedify_message_v2"` by default.
    * @default `"fedify_message_v2"`
    */
-  tableName?: string;
+  readonly tableName?: string;
   /**
    * The channel name to use for the message queue.
    * `"fedify_channel"` by default.
    * @default `"fedify_channel"`
    */
-  channelName?: string;
+  readonly channelName?: string;
   /**
    * Whether the table has been initialized.  `false` by default.
    * @default `false`
    */
-  initialized?: boolean;
+  readonly initialized?: boolean;
   /**
    * The poll interval for the message queue.  5 seconds by default.
    * @default `{ seconds: 5 }`
    */
-  pollInterval?: Temporal.Duration | Temporal.DurationLike;
+  readonly pollInterval?: Temporal.Duration | Temporal.DurationLike;
 }
 /**
  * A message queue that uses PostgreSQL as the underlying storage.
@@ -51,7 +51,7 @@ 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>;
+  enqueueMany(messages: readonly 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.

package/dist/mq.js

@@ -45,46 +45,66 @@ var PostgresMessageQueue = class {
 	async enqueue(message, options) {
 		await this.initialize();
 		const delay = options?.delay ?? Temporal.Duration.from({ seconds: 0 });
+		const orderingKey = options?.orderingKey ?? null;
 		if (options?.delay) logger.debug("Enqueuing a message with a delay of {delay}...", {
 			delay,
-			message
+			message,
+			orderingKey
+		});
+		else logger.debug("Enqueuing a message...", {
+			message,
+			orderingKey
 		});
-		else logger.debug("Enqueuing a message...", { message });
 		await this.#sql`
-      INSERT INTO ${this.#sql(this.#tableName)} (message, delay)
+      INSERT INTO ${this.#sql(this.#tableName)} (message, delay, ordering_key)
       VALUES (
         ${this.#json(message)},
-        ${delay.toString()}
+        ${delay.toString()},
+        ${orderingKey}
       );
     `;
-		logger.debug("Enqueued a message.", { message });
+		logger.debug("Enqueued a message.", {
+			message,
+			orderingKey
+		});
 		await this.#sql.notify(this.#channelName, delay.toString());
 		logger.debug("Notified the message queue channel {channelName}.", {
 			channelName: this.#channelName,
-			message
+			message,
+			orderingKey
 		});
 	}
 	async enqueueMany(messages, options) {
 		if (messages.length === 0) return;
 		await this.initialize();
 		const delay = options?.delay ?? Temporal.Duration.from({ seconds: 0 });
+		const orderingKey = options?.orderingKey ?? null;
 		if (options?.delay) logger.debug("Enqueuing messages with a delay of {delay}...", {
 			delay,
-			messages
+			messages,
+			orderingKey
+		});
+		else logger.debug("Enqueuing messages...", {
+			messages,
+			orderingKey
 		});
-		else logger.debug("Enqueuing messages...", { messages });
 		for (const message of messages) await this.#sql`
-        INSERT INTO ${this.#sql(this.#tableName)} (message, delay)
+        INSERT INTO ${this.#sql(this.#tableName)} (message, delay, ordering_key)
         VALUES (
           ${this.#json(message)},
-          ${delay.toString()}
+          ${delay.toString()},
+          ${orderingKey}
         );
       `;
-		logger.debug("Enqueued messages.", { messages });
+		logger.debug("Enqueued messages.", {
+			messages,
+			orderingKey
+		});
 		await this.#sql.notify(this.#channelName, delay.toString());
 		logger.debug("Notified the message queue channel {channelName}.", {
 			channelName: this.#channelName,
-			messages
+			messages,
+			orderingKey
 		});
 	}
 	async listen(handler, options = {}) {
@@ -92,27 +112,77 @@ var PostgresMessageQueue = class {
 		const { signal } = options;
 		const poll = async () => {
 			while (!signal?.aborted) {
+				let processed = false;
 				const query = this.#sql`
-          DELETE FROM ${this.#sql(this.#tableName)}
-          WHERE id = (
-            SELECT id
+          WITH candidate AS (
+            SELECT id, ordering_key
             FROM ${this.#sql(this.#tableName)}
             WHERE created + delay < CURRENT_TIMESTAMP
+              AND ordering_key IS NULL
             ORDER BY created
             LIMIT 1
+            FOR UPDATE SKIP LOCKED
           )
-          RETURNING message;
+          DELETE FROM ${this.#sql(this.#tableName)}
+          WHERE id IN (SELECT id FROM candidate)
+          RETURNING message, ordering_key;
         `.execute();
 				const cancel = query.cancel.bind(query);
 				signal?.addEventListener("abort", cancel);
-				let i = 0;
-				for (const message of await query) {
+				for (const row of await query) {
 					if (signal?.aborted) return;
-					await handler(message.message);
-					i++;
+					await handler(row.message);
+					processed = true;
 				}
 				signal?.removeEventListener("abort", cancel);
-				if (i < 1) break;
+				if (processed) continue;
+				const attemptedOrderingKeys = /* @__PURE__ */ new Set();
+				while (!signal?.aborted) {
+					const candidateResult = await this.#sql`
+            SELECT id, ordering_key
+            FROM ${this.#sql(this.#tableName)}
+            WHERE created + delay < CURRENT_TIMESTAMP
+              AND ordering_key IS NOT NULL
+              ${attemptedOrderingKeys.size > 0 ? this.#sql`AND ordering_key NOT IN ${this.#sql([...attemptedOrderingKeys])}` : this.#sql``}
+            ORDER BY created
+            LIMIT 1
+          `;
+					if (candidateResult.length === 0) break;
+					const candidate = candidateResult[0];
+					const candidateId = candidate.id;
+					const orderingKey = candidate.ordering_key;
+					attemptedOrderingKeys.add(orderingKey);
+					const lockResult = await this.#sql`
+            SELECT pg_try_advisory_lock(
+              hashtext(${this.#tableName}),
+              hashtext(${orderingKey})
+            ) AS acquired
+          `;
+					if (lockResult[0].acquired) {
+						try {
+							const deleteResult = await this.#sql`
+                DELETE FROM ${this.#sql(this.#tableName)}
+                WHERE id = ${candidateId}
+                RETURNING message, ordering_key
+              `;
+							for (const row of deleteResult) {
+								if (signal?.aborted) return;
+								await handler(row.message);
+								processed = true;
+							}
+						} finally {
+							await this.#sql`
+                SELECT pg_advisory_unlock(
+                  hashtext(${this.#tableName}),
+                  hashtext(${orderingKey})
+                )
+              `;
+						}
+						if (processed) break;
+					}
+				}
+				if (processed) continue;
+				break;
 			}
 		};
 		const timeouts = /* @__PURE__ */ new Set();
@@ -156,8 +226,13 @@ var PostgresMessageQueue = class {
         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
+        created timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
+        ordering_key text
       );
+    `;
+			await this.#sql`
+      ALTER TABLE ${this.#sql(this.#tableName)}
+      ADD COLUMN IF NOT EXISTS ordering_key text;
     `;
 		} catch (error) {
 			if (!(error instanceof postgres.PostgresError && error.constraint_name === "pg_type_typname_nsp_index")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/postgres",
-  "version": "2.0.0-pr.490.2+99a396d5",
+  "version": "2.0.0-pr.559.4+6357309b",
   "description": "PostgreSQL drivers for Fedify",
   "keywords": [
     "fedify",
@@ -70,21 +70,26 @@
   ],
   "dependencies": {
     "@js-temporal/polyfill": "^0.5.1",
-    "@logtape/logtape": "^1.2.2"
+    "@logtape/logtape": "^2.0.0"
   },
   "peerDependencies": {
     "postgres": "^3.4.7",
-    "@fedify/fedify": "^2.0.0-pr.490.2+99a396d5"
+    "@fedify/fedify": "^2.0.0-pr.559.4+6357309b"
   },
   "devDependencies": {
     "@std/async": "npm:@jsr/std__async@^1.0.13",
     "tsdown": "^0.12.9",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "@fedify/fixture": "^2.0.0",
+    "@fedify/testing": "^2.0.0-pr.559.4+6357309b"
   },
   "scripts": {
-    "build": "tsdown",
-    "prepublish": "tsdown",
-    "test": "tsdown && node --experimental-transform-types --test",
-    "test:bun": "tsdown && bun test --timeout=10000"
+    "build:self": "tsdown",
+    "build": "pnpm --filter @fedify/postgres... run build:self",
+    "prepublish": "pnpm build",
+    "pretest": "pnpm build",
+    "test": "node --experimental-transform-types --test",
+    "pretest:bun": "pnpm build",
+    "test:bun": "bun test --timeout=10000"
   }
 }