@fedify/mysql 2.1.0-dev.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+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
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+<!-- deno-fmt-ignore-file -->
+
+@fedify/mysql: MySQL/MariaDB drivers for Fedify
+===============================================
+
+[![JSR][JSR badge]][JSR]
+[![npm][npm badge]][npm]
+
+This package provides [Fedify]'s [`KvStore`] and [`MessageQueue`]
+implementations for MySQL/MariaDB:
+
+ -  [`MysqlKvStore`]
+ -  [`MysqlMessageQueue`]
+
+~~~~ typescript
+import { createFederation } from "@fedify/fedify";
+import { MysqlKvStore, MysqlMessageQueue } from "@fedify/mysql";
+import mysql from "mysql2/promise";
+
+const pool = mysql.createPool("mysql://user:password@localhost/dbname");
+
+const federation = createFederation({
+  kv: new MysqlKvStore(pool),
+  queue: new MysqlMessageQueue(pool),
+});
+~~~~
+
+[JSR badge]: https://jsr.io/badges/@fedify/mysql
+[JSR]: https://jsr.io/@fedify/mysql
+[npm badge]: https://img.shields.io/npm/v/@fedify/mysql?logo=npm
+[npm]: https://www.npmjs.com/package/@fedify/mysql
+[Fedify]: https://fedify.dev/
+[`KvStore`]: https://jsr.io/@fedify/fedify/doc/federation/~/KvStore
+[`MessageQueue`]: https://jsr.io/@fedify/fedify/doc/federation/~/MessageQueue
+[`MysqlKvStore`]: https://jsr.io/@fedify/mysql/doc/~/MysqlKvStore
+[`MysqlMessageQueue`]: https://jsr.io/@fedify/mysql/doc/mq/~/MysqlMessageQueue
+
+
+Installation
+------------
+
+~~~~ sh
+deno add jsr:@fedify/mysql              # Deno
+npm  add     @fedify/mysql mysql2       # npm
+pnpm add     @fedify/mysql mysql2       # pnpm
+yarn add     @fedify/mysql mysql2       # Yarn
+bun  add     @fedify/mysql mysql2       # Bun
+~~~~

package/dist/_virtual/rolldown_runtime.cjs

@@ -0,0 +1,33 @@
+
+        const { Temporal } = require("@js-temporal/polyfill");
+      
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+
+Object.defineProperty(exports, '__toESM', {
+  enumerable: true,
+  get: function () {
+    return __toESM;
+  }
+});

package/dist/kv.cjs

@@ -0,0 +1,235 @@
+
+        const { Temporal } = require("@js-temporal/polyfill");
+      
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const es_toolkit = require_rolldown_runtime.__toESM(require("es-toolkit"));
+const __logtape_logtape = require_rolldown_runtime.__toESM(require("@logtape/logtape"));
+
+//#region src/kv.ts
+const logger = (0, __logtape_logtape.getLogger)([
+	"fedify",
+	"mysql",
+	"kv"
+]);
+/**
+* A key-value store that uses MySQL (or MariaDB) as the underlying storage.
+*
+* @example
+* ```ts
+* import { createFederation } from "@fedify/fedify";
+* import { MysqlKvStore } from "@fedify/mysql";
+* import mysql from "mysql2/promise";
+*
+* const pool = mysql.createPool("mysql://user:pass@localhost/db");
+*
+* const federation = createFederation({
+*   // ...
+*   kv: new MysqlKvStore(pool),
+* });
+* ```
+*
+* @since 2.1.0
+*/
+var MysqlKvStore = class {
+	#pool;
+	#tableName;
+	#expireCleanupRate;
+	#initialized;
+	/**
+	* Creates a new MySQL key-value store.
+	* @param pool The MySQL connection pool to use.
+	* @param options The options for the key-value store.
+	* @since 2.1.0
+	*/
+	constructor(pool, options = {}) {
+		this.#pool = pool;
+		const tableName = options.tableName ?? "fedify_kv";
+		if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(tableName)) throw new RangeError(`Invalid table name: ${JSON.stringify(tableName)}. Table names must start with a letter or underscore and contain only letters, digits, and underscores.`);
+		if (tableName.length > 50) throw new RangeError(`Invalid table name: ${JSON.stringify(tableName)}. Table names must be at most 50 characters long (MySQL identifier limit is 64 chars; the derived index "idx_<name>_expires" uses 12 more).`);
+		this.#tableName = tableName;
+		const expireCleanupRate = options.expireCleanupRate ?? 1;
+		if (expireCleanupRate < 0 || expireCleanupRate > 1) throw new RangeError(`Invalid expireCleanupRate: ${expireCleanupRate}. Must be a number between 0 and 1 inclusive.`);
+		this.#expireCleanupRate = expireCleanupRate;
+		this.#initialized = options.initialized ?? false;
+	}
+	async #expire() {
+		if (this.#expireCleanupRate <= 0) return;
+		if (this.#expireCleanupRate < 1 && Math.random() >= this.#expireCleanupRate) return;
+		await this.#pool.query(`DELETE FROM \`${this.#tableName}\`
+       WHERE \`expires\` IS NOT NULL AND \`expires\` < NOW(6)`);
+	}
+	/**
+	* {@inheritDoc KvStore.get}
+	* @since 2.1.0
+	*/
+	async get(key) {
+		await this.initialize();
+		const serializedKey = JSON.stringify([...key]);
+		const [rows] = await this.#pool.query(`SELECT \`value\` FROM \`${this.#tableName}\`
+       WHERE \`key\` = ?
+         AND (\`expires\` IS NULL OR \`expires\` > NOW(6))`, [serializedKey]);
+		if (rows.length < 1) return void 0;
+		return rows[0].value;
+	}
+	/**
+	* {@inheritDoc KvStore.set}
+	* @since 2.1.0
+	*/
+	async set(key, value, options) {
+		if (value === void 0) return;
+		await this.initialize();
+		const serializedKey = JSON.stringify([...key]);
+		const jsonValue = JSON.stringify(value);
+		if (options?.ttl != null) {
+			const ttlSeconds = durationToSeconds(options.ttl);
+			await this.#pool.query(`INSERT INTO \`${this.#tableName}\` (\`key\`, \`value\`, \`expires\`)
+         VALUES (?, CAST(? AS JSON),
+                 DATE_ADD(NOW(6), INTERVAL ? SECOND))
+         ON DUPLICATE KEY UPDATE
+           \`value\` = VALUES(\`value\`),
+           \`expires\` = VALUES(\`expires\`)`, [
+				serializedKey,
+				jsonValue,
+				ttlSeconds
+			]);
+		} else await this.#pool.query(`INSERT INTO \`${this.#tableName}\` (\`key\`, \`value\`, \`expires\`)
+         VALUES (?, CAST(? AS JSON), NULL)
+         ON DUPLICATE KEY UPDATE
+           \`value\` = VALUES(\`value\`),
+           \`expires\` = NULL`, [serializedKey, jsonValue]);
+		await this.#expire();
+	}
+	/**
+	* {@inheritDoc KvStore.delete}
+	* @since 2.1.0
+	*/
+	async delete(key) {
+		await this.initialize();
+		const serializedKey = JSON.stringify([...key]);
+		await this.#pool.query(`DELETE FROM \`${this.#tableName}\` WHERE \`key\` = ?`, [serializedKey]);
+		await this.#expire();
+	}
+	/**
+	* {@inheritDoc KvStore.cas}
+	* @since 2.1.0
+	*/
+	async cas(key, expectedValue, newValue, options) {
+		await this.initialize();
+		const serializedKey = JSON.stringify([...key]);
+		let conn;
+		try {
+			conn = await this.#pool.getConnection();
+			await conn.beginTransaction();
+			const [rows] = await conn.query(`SELECT
+           \`value\`,
+           (\`expires\` IS NOT NULL AND \`expires\` <= NOW(6)) AS \`is_expired\`
+         FROM \`${this.#tableName}\`
+         WHERE \`key\` = ?
+         FOR UPDATE`, [serializedKey]);
+			const row = rows[0];
+			const currentValue = !row || row.is_expired ? void 0 : row.value;
+			if (!(0, es_toolkit.isEqual)(currentValue, expectedValue)) {
+				await conn.rollback();
+				return false;
+			}
+			if (newValue === void 0) await conn.query(`DELETE FROM \`${this.#tableName}\` WHERE \`key\` = ?`, [serializedKey]);
+			else {
+				const jsonValue = JSON.stringify(newValue);
+				if (options?.ttl != null) {
+					const ttlSeconds = durationToSeconds(options.ttl);
+					await conn.query(`INSERT INTO \`${this.#tableName}\`
+               (\`key\`, \`value\`, \`expires\`)
+             VALUES (?, CAST(? AS JSON),
+                     DATE_ADD(NOW(6), INTERVAL ? SECOND))
+             ON DUPLICATE KEY UPDATE
+               \`value\` = VALUES(\`value\`),
+               \`expires\` = VALUES(\`expires\`)`, [
+						serializedKey,
+						jsonValue,
+						ttlSeconds
+					]);
+				} else await conn.query(`INSERT INTO \`${this.#tableName}\`
+               (\`key\`, \`value\`, \`expires\`)
+             VALUES (?, CAST(? AS JSON), NULL)
+             ON DUPLICATE KEY UPDATE
+               \`value\` = VALUES(\`value\`),
+               \`expires\` = NULL`, [serializedKey, jsonValue]);
+			}
+			await conn.commit();
+			await this.#expire();
+			return true;
+		} catch (e) {
+			if (conn) await conn.rollback();
+			throw e;
+		} finally {
+			if (conn) conn.release();
+		}
+	}
+	/**
+	* {@inheritDoc KvStore.list}
+	* @since 2.1.0
+	*/
+	async *list(prefix) {
+		await this.initialize();
+		let rows;
+		if (prefix == null || prefix.length === 0) [rows] = await this.#pool.query(`SELECT \`key\`, \`value\` FROM \`${this.#tableName}\`
+         WHERE \`expires\` IS NULL OR \`expires\` > NOW(6)
+         ORDER BY \`key\``);
+		else {
+			const serializedPrefix = JSON.stringify([...prefix]);
+			const likePrefix = serializedPrefix.slice(0, -1).replace(/[%_\\]/g, "\\$&") + ",%";
+			[rows] = await this.#pool.query(`SELECT \`key\`, \`value\` FROM \`${this.#tableName}\`
+         WHERE (\`key\` = ? OR \`key\` LIKE ? ESCAPE '\\\\')
+           AND (\`expires\` IS NULL OR \`expires\` > NOW(6))
+         ORDER BY \`key\``, [serializedPrefix, likePrefix]);
+		}
+		for (const row of rows) yield {
+			key: JSON.parse(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.
+	*
+	* @since 2.1.0
+	*/
+	async initialize() {
+		if (this.#initialized) return;
+		logger.debug("Initializing the key-value store table {tableName}...", { tableName: this.#tableName });
+		await this.#pool.query(`CREATE TABLE IF NOT EXISTS \`${this.#tableName}\` (
+        \`key\` VARCHAR(768) NOT NULL,
+        \`value\` JSON NOT NULL,
+        \`expires\` DATETIME(6) NULL DEFAULT NULL,
+        PRIMARY KEY (\`key\`)
+      ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin`);
+		try {
+			await this.#pool.query(`CREATE INDEX \`idx_${this.#tableName}_expires\`
+         ON \`${this.#tableName}\` (\`expires\`)`);
+		} catch (e) {
+			if (e.code !== "ER_DUP_KEYNAME") throw e;
+		}
+		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.  Resets the initialized flag so that
+	* {@link MysqlKvStore.initialize} can recreate the table on the next call.
+	*
+	* @since 2.1.0
+	*/
+	async drop() {
+		await this.#pool.query(`DROP TABLE IF EXISTS \`${this.#tableName}\``);
+		this.#initialized = false;
+	}
+};
+function durationToSeconds(duration) {
+	return duration.total({
+		unit: "second",
+		relativeTo: Temporal.Now.plainDateTimeISO()
+	});
+}
+
+//#endregion
+exports.MysqlKvStore = MysqlKvStore;

package/dist/kv.d.cts

@@ -0,0 +1,103 @@
+import { KvKey, KvStore, KvStoreListEntry, KvStoreSetOptions } from "@fedify/fedify";
+import { Pool } from "mysql2/promise";
+
+//#region src/kv.d.ts
+/**
+* Options for the MySQL key-value store.
+*
+* @since 2.1.0
+*/
+interface MysqlKvStoreOptions {
+  /**
+  * The table name to use for the key-value store.
+  * `"fedify_kv"` by default.
+  * @default `"fedify_kv"`
+  * @since 2.1.0
+  */
+  readonly tableName?: string;
+  /**
+  * Whether the table has been initialized.  `false` by default.
+  * @default `false`
+  * @since 2.1.0
+  */
+  readonly initialized?: boolean;
+  /**
+  * The probability (between 0 and 1, inclusive) that expired entries are
+  * cleaned up on each mutation.  Defaults to `1` (always clean up).
+  * Set to `0` to disable automatic expiry cleanup entirely.
+  * @default `1`
+  * @since 2.1.0
+  */
+  readonly expireCleanupRate?: number;
+}
+/**
+* A key-value store that uses MySQL (or MariaDB) as the underlying storage.
+*
+* @example
+* ```ts
+* import { createFederation } from "@fedify/fedify";
+* import { MysqlKvStore } from "@fedify/mysql";
+* import mysql from "mysql2/promise";
+*
+* const pool = mysql.createPool("mysql://user:pass@localhost/db");
+*
+* const federation = createFederation({
+*   // ...
+*   kv: new MysqlKvStore(pool),
+* });
+* ```
+*
+* @since 2.1.0
+*/
+declare class MysqlKvStore implements KvStore {
+  #private;
+  /**
+  * Creates a new MySQL key-value store.
+  * @param pool The MySQL connection pool to use.
+  * @param options The options for the key-value store.
+  * @since 2.1.0
+  */
+  constructor(pool: Pool, options?: MysqlKvStoreOptions);
+  /**
+  * {@inheritDoc KvStore.get}
+  * @since 2.1.0
+  */
+  get<T = unknown>(key: KvKey): Promise<T | undefined>;
+  /**
+  * {@inheritDoc KvStore.set}
+  * @since 2.1.0
+  */
+  set(key: KvKey, value: unknown, options?: KvStoreSetOptions | undefined): Promise<void>;
+  /**
+  * {@inheritDoc KvStore.delete}
+  * @since 2.1.0
+  */
+  delete(key: KvKey): Promise<void>;
+  /**
+  * {@inheritDoc KvStore.cas}
+  * @since 2.1.0
+  */
+  cas(key: KvKey, expectedValue: unknown, newValue: unknown, options?: KvStoreSetOptions): Promise<boolean>;
+  /**
+  * {@inheritDoc KvStore.list}
+  * @since 2.1.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.
+  *
+  * @since 2.1.0
+  */
+  initialize(): Promise<void>;
+  /**
+  * Drops the table used by the key-value store.  Does nothing if the table
+  * does not exist.  Resets the initialized flag so that
+  * {@link MysqlKvStore.initialize} can recreate the table on the next call.
+  *
+  * @since 2.1.0
+  */
+  drop(): Promise<void>;
+}
+//#endregion
+export { MysqlKvStore, MysqlKvStoreOptions };

package/dist/kv.d.ts

@@ -0,0 +1,104 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { KvKey, KvStore, KvStoreListEntry, KvStoreSetOptions } from "@fedify/fedify";
+import { Pool } from "mysql2/promise";
+
+//#region src/kv.d.ts
+/**
+* Options for the MySQL key-value store.
+*
+* @since 2.1.0
+*/
+interface MysqlKvStoreOptions {
+  /**
+  * The table name to use for the key-value store.
+  * `"fedify_kv"` by default.
+  * @default `"fedify_kv"`
+  * @since 2.1.0
+  */
+  readonly tableName?: string;
+  /**
+  * Whether the table has been initialized.  `false` by default.
+  * @default `false`
+  * @since 2.1.0
+  */
+  readonly initialized?: boolean;
+  /**
+  * The probability (between 0 and 1, inclusive) that expired entries are
+  * cleaned up on each mutation.  Defaults to `1` (always clean up).
+  * Set to `0` to disable automatic expiry cleanup entirely.
+  * @default `1`
+  * @since 2.1.0
+  */
+  readonly expireCleanupRate?: number;
+}
+/**
+* A key-value store that uses MySQL (or MariaDB) as the underlying storage.
+*
+* @example
+* ```ts
+* import { createFederation } from "@fedify/fedify";
+* import { MysqlKvStore } from "@fedify/mysql";
+* import mysql from "mysql2/promise";
+*
+* const pool = mysql.createPool("mysql://user:pass@localhost/db");
+*
+* const federation = createFederation({
+*   // ...
+*   kv: new MysqlKvStore(pool),
+* });
+* ```
+*
+* @since 2.1.0
+*/
+declare class MysqlKvStore implements KvStore {
+  #private;
+  /**
+  * Creates a new MySQL key-value store.
+  * @param pool The MySQL connection pool to use.
+  * @param options The options for the key-value store.
+  * @since 2.1.0
+  */
+  constructor(pool: Pool, options?: MysqlKvStoreOptions);
+  /**
+  * {@inheritDoc KvStore.get}
+  * @since 2.1.0
+  */
+  get<T = unknown>(key: KvKey): Promise<T | undefined>;
+  /**
+  * {@inheritDoc KvStore.set}
+  * @since 2.1.0
+  */
+  set(key: KvKey, value: unknown, options?: KvStoreSetOptions | undefined): Promise<void>;
+  /**
+  * {@inheritDoc KvStore.delete}
+  * @since 2.1.0
+  */
+  delete(key: KvKey): Promise<void>;
+  /**
+  * {@inheritDoc KvStore.cas}
+  * @since 2.1.0
+  */
+  cas(key: KvKey, expectedValue: unknown, newValue: unknown, options?: KvStoreSetOptions): Promise<boolean>;
+  /**
+  * {@inheritDoc KvStore.list}
+  * @since 2.1.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.
+  *
+  * @since 2.1.0
+  */
+  initialize(): Promise<void>;
+  /**
+  * Drops the table used by the key-value store.  Does nothing if the table
+  * does not exist.  Resets the initialized flag so that
+  * {@link MysqlKvStore.initialize} can recreate the table on the next call.
+  *
+  * @since 2.1.0
+  */
+  drop(): Promise<void>;
+}
+//#endregion
+export { MysqlKvStore, MysqlKvStoreOptions };