Relax MySQL pool constructor types

Accept the structural MySQL pool shape in MysqlKvStore and
MysqlMessageQueue instead of tying the public constructors to a
specific mysql2 Pool type identity.

This fixes TypeScript assignment failures when applications resolve
mysql2 through multiple type sources or different package versions,
including the docs twoslash build path, without changing runtime
behavior.

Update CHANGES.md to describe the fix as a user-visible TypeScript
compatibility bug fix for @fedify/mysql.

Assisted-by: Codex:gpt-5.4

Author: dahlia

CHANGES.md

@@ -8,6 +8,15 @@ Version 2.1.9
 
 To be released.
 
+### @fedify/mysql
+
+ -  Fixed a TypeScript type mismatch in `MysqlKvStore` and
+    `MysqlMessageQueue` that could reject valid `mysql2` pools when an
+    application resolved `mysql2` through multiple type sources or different
+    package versions.  The constructors now accept the structural pool shape
+    they actually use, so mixed Deno/npm setups and monorepos no longer need
+    casts or `@ts-expect-error` workarounds.
+
 
 Version 2.1.8
 -------------

packages/mysql/src/kv.ts

@@ -6,10 +6,28 @@ import type {
 } from "@fedify/fedify";
 import { isEqual } from "es-toolkit";
 import { getLogger } from "@logtape/logtape";
-import type { Pool, PoolConnection, RowDataPacket } from "mysql2/promise";
+import type { RowDataPacket } from "mysql2/promise";
 
 const logger = getLogger(["fedify", "mysql", "kv"]);
 
+interface MysqlQueryable {
+  query<TRows = unknown>(
+    sql: string,
+    values?: unknown,
+  ): Promise<[TRows, unknown]>;
+}
+
+interface MysqlPoolConnection extends MysqlQueryable {
+  beginTransaction(): Promise<void>;
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+  release(): void;
+}
+
+interface MysqlPool extends MysqlQueryable {
+  getConnection(): Promise<MysqlPoolConnection>;
+}
+
 /**
  * Options for the MySQL key-value store.
  *
@@ -61,7 +79,7 @@ export interface MysqlKvStoreOptions {
  * @since 2.1.0
  */
 export class MysqlKvStore implements KvStore {
-  readonly #pool: Pool;
+  readonly #pool: MysqlPool;
   readonly #tableName: string;
   readonly #expireCleanupRate: number;
   #initialized: boolean;
@@ -72,7 +90,7 @@ export class MysqlKvStore implements KvStore {
    * @param options The options for the key-value store.
    * @since 2.1.0
    */
-  constructor(pool: Pool, options: MysqlKvStoreOptions = {}) {
+  constructor(pool: MysqlPool, options: MysqlKvStoreOptions = {}) {
     this.#pool = pool;
     const tableName = options.tableName ?? "fedify_kv";
     if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(tableName)) {
@@ -198,7 +216,7 @@ export class MysqlKvStore implements KvStore {
   ): Promise<boolean> {
     await this.initialize();
     const serializedKey = JSON.stringify([...key]);
-    let conn: PoolConnection | undefined;
+    let conn: MysqlPoolConnection | undefined;
     try {
       conn = await this.#pool.getConnection();
       await conn.beginTransaction();

packages/mysql/src/mq.ts

@@ -4,7 +4,7 @@ import type {
   MessageQueueListenOptions,
 } from "@fedify/fedify";
 import { getLogger } from "@logtape/logtape";
-import type { Pool, PoolConnection, RowDataPacket } from "mysql2/promise";
+import type { RowDataPacket } from "mysql2/promise";
 
 const logger = getLogger(["fedify", "mysql", "mq"]);
 const INITIALIZE_MAX_ATTEMPTS = 5;
@@ -14,6 +14,24 @@ const INITIALIZE_BACKOFF_MS = 10;
 // the cost of a slightly larger result set from the GROUP BY query.
 const ORDERING_KEY_CANDIDATE_LIMIT = 10;
 
+interface MysqlQueryable {
+  query<TRows = unknown>(
+    sql: string,
+    values?: unknown,
+  ): Promise<[TRows, unknown]>;
+}
+
+interface MysqlPoolConnection extends MysqlQueryable {
+  beginTransaction(): Promise<void>;
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+  release(): void;
+}
+
+interface MysqlPool extends MysqlQueryable {
+  getConnection(): Promise<MysqlPoolConnection>;
+}
+
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -144,7 +162,7 @@ export class MysqlMessageQueue implements MessageQueue {
    */
   readonly nativeRetrial = false;
 
-  readonly #pool: Pool;
+  readonly #pool: MysqlPool;
   readonly #tableName: string;
   readonly #pollIntervalMs: number;
   readonly #handlerTimeoutMs: number;
@@ -157,7 +175,7 @@ export class MysqlMessageQueue implements MessageQueue {
    * @param options Options for the message queue.
    * @since 2.1.0
    */
-  constructor(pool: Pool, options: MysqlMessageQueueOptions = {}) {
+  constructor(pool: MysqlPool, options: MysqlMessageQueueOptions = {}) {
     this.#pool = pool;
     const tableName = options.tableName ?? "fedify_mq";
     if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(tableName)) {
@@ -264,7 +282,7 @@ export class MysqlMessageQueue implements MessageQueue {
       delayMs * 1000 + index,
       orderingKey,
     ]);
-    let conn: PoolConnection | undefined;
+    let conn: MysqlPoolConnection | undefined;
     try {
       conn = await this.#pool.getConnection();
       await conn.beginTransaction();
@@ -333,7 +351,7 @@ export class MysqlMessageQueue implements MessageQueue {
           if (signal?.aborted) break;
           const lockName = getMysqlLockName(this.#tableName, orderingKey);
 
-          let conn: PoolConnection | undefined;
+          let conn: MysqlPoolConnection | undefined;
           try {
             conn = await this.#pool.getConnection();
             const [lockResult] = await conn.query<RowDataPacket[]>(
@@ -416,7 +434,7 @@ export class MysqlMessageQueue implements MessageQueue {
    * Returns `undefined` when no such message is available.
    */
   async #dequeueWithoutOrderingKey(): Promise<unknown> {
-    let conn: PoolConnection | undefined;
+    let conn: MysqlPoolConnection | undefined;
     try {
       conn = await this.#pool.getConnection();
       await conn.beginTransaction();
@@ -474,7 +492,7 @@ export class MysqlMessageQueue implements MessageQueue {
    * Returns `undefined` when no ready message exists for the ordering key.
    */
   async #dequeueOrderedMessage(
-    conn: PoolConnection,
+    conn: MysqlPoolConnection,
     orderingKey: string,
   ): Promise<unknown> {
     await conn.beginTransaction();