matrix-nodejs-homeserver 0.0.0-stage → 0.2.0

package/dist/storage/sql.js

@@ -0,0 +1,274 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/storage/sql.ts
+const OPS = {
+	eq: "=",
+	ne: "<>",
+	lt: "<",
+	lte: "<=",
+	gt: ">",
+	gte: ">="
+};
+/**
+* Generic SQL adapter. Works with any driver that can run parameterised
+* queries; see `sqliteAdapter` and `postgresAdapter` for ready-made wrappers.
+*/
+function sqlAdapter({ dialect, executor: rootExecutor, tablePrefix = "", transaction }) {
+	let schema = {};
+	const q = (ident) => dialect === "mysql" ? `\`${ident}\`` : `"${ident}"`;
+	const t = (model) => q(tablePrefix + model);
+	const columnType = (type, isKey) => {
+		switch (type) {
+			case "string": return dialect === "mysql" ? isKey ? "VARCHAR(255)" : "TEXT" : "TEXT";
+			case "number": return dialect === "sqlite" ? "INTEGER" : "BIGINT";
+			case "boolean": return dialect === "postgres" ? "BOOLEAN" : "INTEGER";
+			case "json": return dialect === "mysql" ? "LONGTEXT" : "TEXT";
+		}
+	};
+	const columnsOf = async (executor, table) => {
+		const rows = dialect === "sqlite" ? await executor.query(`PRAGMA table_info(${q(table)})`, []) : dialect === "postgres" ? await executor.query("SELECT column_name AS name FROM information_schema.columns WHERE table_schema = current_schema() AND table_name = $1", [table]) : await executor.query("SELECT COLUMN_NAME AS name FROM information_schema.columns WHERE table_schema = DATABASE() AND table_name = ?", [table]);
+		return new Set(rows.map((r) => String(r.name)));
+	};
+	const fieldType = (model, field) => schema[model]?.fields[field]?.type ?? "string";
+	const toDb = (model, field, value) => {
+		if (value === void 0 || value === null) return null;
+		switch (fieldType(model, field)) {
+			case "json": return JSON.stringify(value);
+			case "boolean": return dialect === "postgres" ? !!value : value ? 1 : 0;
+			default: return value;
+		}
+	};
+	const fromDb = (model, row) => {
+		const out = {};
+		for (const [field, value] of Object.entries(row)) {
+			if (value === null || value === void 0) {
+				out[field] = null;
+				continue;
+			}
+			switch (fieldType(model, field)) {
+				case "json":
+					out[field] = typeof value === "string" ? JSON.parse(value) : value;
+					break;
+				case "boolean":
+					out[field] = value === true || value === 1 || value === "1" || value === 1n;
+					break;
+				case "number":
+					out[field] = Number(value);
+					break;
+				default: out[field] = value;
+			}
+		}
+		return out;
+	};
+	const placeholder = (i) => dialect === "postgres" ? `$${i}` : "?";
+	const buildWhere = (model, where = [], params) => {
+		if (where.length === 0) return "";
+		return ` WHERE ${where.map((w) => {
+			const op = w.operator ?? "eq";
+			if (op === "in") {
+				const values = w.value;
+				if (values.length === 0) return "1=0";
+				const ph = values.map((v) => {
+					params.push(toDb(model, w.field, v));
+					return placeholder(params.length);
+				});
+				return `${q(w.field)} IN (${ph.join(", ")})`;
+			}
+			if (w.value === null || w.value === void 0) {
+				if (op === "eq") return `${q(w.field)} IS NULL`;
+				if (op === "ne") return `${q(w.field)} IS NOT NULL`;
+			}
+			params.push(toDb(model, w.field, w.value));
+			return `${q(w.field)} ${OPS[op]} ${placeholder(params.length)}`;
+		}).join(" AND ")}`;
+	};
+	const build = (executor, inTx) => {
+		const insert = async (model, data, mode) => {
+			const fields = Object.keys(data).filter((k) => data[k] !== void 0);
+			const params = fields.map((f) => toDb(model, f, data[f]));
+			const cols = fields.map(q).join(", ");
+			const ph = fields.map((_, i) => placeholder(i + 1)).join(", ");
+			let sql = `INSERT INTO ${t(model)} (${cols}) VALUES (${ph})`;
+			if (mode === "upsert") {
+				const pk = schema[model]?.primaryKey ?? [];
+				const rest = fields.filter((f) => !pk.includes(f));
+				if (dialect === "mysql") sql += rest.length ? ` ON DUPLICATE KEY UPDATE ${rest.map((f) => `${q(f)} = VALUES(${q(f)})`).join(", ")}` : ` ON DUPLICATE KEY UPDATE ${q(pk[0])} = ${q(pk[0])}`;
+				else sql += ` ON CONFLICT (${pk.map(q).join(", ")}) DO ${rest.length ? `UPDATE SET ${rest.map((f) => `${q(f)} = excluded.${q(f)}`).join(", ")}` : "NOTHING"}`;
+			}
+			await executor.execute(sql, params);
+		};
+		const adapter = {
+			async migrate(s) {
+				schema = s;
+				for (const [model, def] of Object.entries(s)) {
+					const cols = Object.entries(def.fields).map(([name, f]) => {
+						const isKey = def.primaryKey.includes(name) || (def.indexes ?? []).some((i) => i.includes(name));
+						return `${q(name)} ${columnType(f.type, isKey)}${f.required === false ? "" : " NOT NULL"}`;
+					});
+					cols.push(`PRIMARY KEY (${def.primaryKey.map(q).join(", ")})`);
+					const ine = "IF NOT EXISTS";
+					await executor.execute(`CREATE TABLE ${ine} ${t(model)} (${cols.join(", ")})`, []);
+					const existing = await columnsOf(executor, tablePrefix + model);
+					for (const [name, f] of Object.entries(def.fields)) {
+						if (existing.has(name)) continue;
+						await executor.execute(`ALTER TABLE ${t(model)} ADD COLUMN ${q(name)} ${columnType(f.type, false)}`, []);
+					}
+					for (const index of def.indexes ?? []) {
+						const name = q(`idx_${tablePrefix}${model}_${index.join("_")}`);
+						if (dialect === "mysql") try {
+							await executor.execute(`CREATE INDEX ${name} ON ${t(model)} (${index.map(q).join(", ")})`, []);
+						} catch {}
+						else await executor.execute(`CREATE INDEX ${ine} ${name} ON ${t(model)} (${index.map(q).join(", ")})`, []);
+					}
+				}
+			},
+			create: (model, data) => insert(model, data, "insert"),
+			upsert: (model, data) => insert(model, data, "upsert"),
+			async findOne(model, where) {
+				const params = [];
+				const rows = await executor.query(`SELECT * FROM ${t(model)}${buildWhere(model, where, params)} LIMIT 1`, params);
+				return rows[0] ? fromDb(model, rows[0]) : null;
+			},
+			async findMany(model, opts = {}) {
+				const params = [];
+				let sql = `SELECT * FROM ${t(model)}${buildWhere(model, opts.where, params)}`;
+				if (opts.sortBy) sql += ` ORDER BY ${q(opts.sortBy.field)} ${opts.sortBy.direction === "asc" ? "ASC" : "DESC"}`;
+				if (opts.limit !== void 0) sql += ` LIMIT ${Math.max(0, Math.floor(opts.limit))}`;
+				return (await executor.query(sql, params)).map((r) => fromDb(model, r));
+			},
+			async update(model, where, data) {
+				const fields = Object.keys(data).filter((k) => data[k] !== void 0);
+				if (fields.length === 0) return 0;
+				const params = fields.map((f) => toDb(model, f, data[f]));
+				const set = fields.map((f, i) => `${q(f)} = ${placeholder(i + 1)}`).join(", ");
+				return executor.execute(`UPDATE ${t(model)} SET ${set}${buildWhere(model, where, params)}`, params);
+			},
+			async delete(model, where) {
+				const params = [];
+				return executor.execute(`DELETE FROM ${t(model)}${buildWhere(model, where, params)}`, params);
+			},
+			async max(model, field) {
+				const m = (await executor.query(`SELECT MAX(${q(field)}) AS m FROM ${t(model)}`, []))[0]?.m;
+				return m === null || m === void 0 ? null : Number(m);
+			}
+		};
+		if (transaction) adapter.transaction = (fn) => inTx ? fn(adapter) : transaction((ex) => fn(build(ex, true)));
+		return adapter;
+	};
+	return build(rootExecutor, false);
+}
+/** SQLite adapter for `node:sqlite` (`new DatabaseSync(path)`) or `better-sqlite3`. */
+function sqliteAdapter(db, options = {}) {
+	try {
+		db.exec("PRAGMA journal_mode = WAL");
+	} catch {}
+	const cache = /* @__PURE__ */ new Map();
+	const stmt = (sql) => {
+		let s = cache.get(sql);
+		if (!s) cache.set(sql, s = db.prepare(sql));
+		return s;
+	};
+	const inTransaction = new AsyncLocalStorage();
+	let gate = Promise.resolve();
+	const waitGate = async () => {
+		if (!inTransaction.getStore()) await gate;
+	};
+	const executor = {
+		async query(sql, params) {
+			await waitGate();
+			return stmt(sql).all(...params);
+		},
+		async execute(sql, params) {
+			await waitGate();
+			return Number(stmt(sql).run(...params).changes);
+		}
+	};
+	return sqlAdapter({
+		dialect: "sqlite",
+		tablePrefix: options.tablePrefix,
+		executor,
+		async transaction(fn) {
+			if (inTransaction.getStore()) return fn(executor);
+			const previous = gate;
+			let release;
+			gate = new Promise((r) => release = r);
+			await previous;
+			try {
+				return await inTransaction.run(true, async () => {
+					db.exec("BEGIN IMMEDIATE");
+					try {
+						const result = await fn(executor);
+						db.exec("COMMIT");
+						return result;
+					} catch (err) {
+						db.exec("ROLLBACK");
+						throw err;
+					}
+				});
+			} finally {
+				release();
+			}
+		}
+	});
+}
+const pgExecutor = (conn) => ({
+	async query(sql, params) {
+		return (await conn.query(sql, params)).rows;
+	},
+	async execute(sql, params) {
+		return (await conn.query(sql, params)).rowCount ?? 0;
+	}
+});
+/** PostgreSQL adapter for `pg` (node-postgres). Pass a `Pool` to get transactions. */
+function postgresAdapter(pool, options = {}) {
+	return sqlAdapter({
+		dialect: "postgres",
+		tablePrefix: options.tablePrefix,
+		executor: pgExecutor(pool),
+		transaction: pool.connect ? async (fn) => {
+			const client = await pool.connect();
+			try {
+				await client.query("BEGIN");
+				const result = await fn(pgExecutor(client));
+				await client.query("COMMIT");
+				return result;
+			} catch (err) {
+				await client.query("ROLLBACK").catch(() => {});
+				throw err;
+			} finally {
+				client.release();
+			}
+		} : void 0
+	});
+}
+const mysqlExecutor = (conn) => ({
+	async query(sql, params) {
+		return (await conn.query(sql, params))[0];
+	},
+	async execute(sql, params) {
+		return (await conn.query(sql, params))[0]?.affectedRows ?? 0;
+	}
+});
+/** MySQL / MariaDB adapter for `mysql2/promise` pools. */
+function mysqlAdapter(pool, options = {}) {
+	return sqlAdapter({
+		dialect: "mysql",
+		tablePrefix: options.tablePrefix,
+		executor: mysqlExecutor(pool),
+		transaction: pool.getConnection ? async (fn) => {
+			const conn = await pool.getConnection();
+			try {
+				await conn.query("START TRANSACTION");
+				const result = await fn(mysqlExecutor(conn));
+				await conn.query("COMMIT");
+				return result;
+			} catch (err) {
+				await conn.query("ROLLBACK").catch(() => {});
+				throw err;
+			} finally {
+				conn.release();
+			}
+		} : void 0
+	});
+}
+//#endregion
+export { mysqlAdapter, postgresAdapter, sqlAdapter, sqliteAdapter };

package/dist/storage/types.d.ts

@@ -0,0 +1,55 @@
+//#region src/storage/types.d.ts
+export type FieldType = "string" | "number" | "boolean" | "json";
+export interface FieldDef {
+  type: FieldType;
+  /** Defaults to true. Nullable fields may be omitted on create. */
+  required?: boolean;
+}
+export interface ModelDef {
+  fields: Record<string, FieldDef>;
+  /** Primary key, possibly composite. */
+  primaryKey: string[];
+  /** Secondary indexes to create (SQL adapters). */
+  indexes?: string[][];
+}
+export type Schema = Record<string, ModelDef>;
+export type Operator = "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in";
+export interface WhereClause {
+  field: string;
+  value: unknown;
+  /** Defaults to "eq". */
+  operator?: Operator;
+}
+export type Row = Record<string, any>;
+export interface FindManyOptions {
+  where?: WhereClause[];
+  sortBy?: {
+    field: string;
+    direction: "asc" | "desc";
+  };
+  limit?: number;
+}
+/**
+ * A storage backend. Implement this interface to plug in any database
+ * (the "raw adapter"), or use one of the bundled adapters.
+ * All `where` clauses are combined with AND.
+ */
+export interface DatabaseAdapter {
+  /** Create tables / collections for the given schema. Must be idempotent. */
+  migrate?(schema: Schema): Promise<void>;
+  create(model: string, data: Row): Promise<void>;
+  /** Insert or replace by primary key. */
+  upsert(model: string, data: Row): Promise<void>;
+  findOne(model: string, where: WhereClause[]): Promise<Row | null>;
+  findMany(model: string, options?: FindManyOptions): Promise<Row[]>;
+  update(model: string, where: WhereClause[], data: Row): Promise<number>;
+  delete(model: string, where: WhereClause[]): Promise<number>;
+  /** Maximum value of a numeric field, or null if there are no rows. */
+  max(model: string, field: string): Promise<number | null>;
+  /**
+   * Run `fn` atomically: either all of its writes are applied or none are.
+   * Optional; without it, writes are applied one by one.
+   */
+  transaction?<T>(fn: (tx: DatabaseAdapter) => Promise<T>): Promise<T>;
+}
+//#endregion

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "matrix-nodejs-homeserver",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "A framework- and database-agnostic Matrix homeserver library for Node.js",
+  "keywords": [
+    "chat",
+    "e2ee",
+    "federation",
+    "homeserver",
+    "matrix"
+  ],
+  "homepage": "https://github.com/k18k/matrix-nodejs-homeserver#readme",
+  "bugs": {
+    "url": "https://github.com/k18k/matrix-nodejs-homeserver/issues"
+  },
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/k18k/matrix-nodejs-homeserver.git"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "imports": {
+    "#*": "./src/*"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "oxlint",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "build": "tsdown",
+    "prepare": "npm run build",
+    "start:example": "node examples/node-http.ts",
+    "start:multi-node-example": "node examples/multi-node.ts",
+    "changeset": "changeset",
+    "version-packages": "changeset version && oxfmt package.json",
+    "release": "changeset publish"
+  },
+  "dependencies": {
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^3.0.3",
+    "@types/node": "^26.6.5",
+    "oxfmt": "^0.73.0",
+    "oxlint": "^1.88.0",
+    "tsdown": "^0.23.1",
+    "typescript": "7.0.2"
+  },
+  "engines": {
+    "node": ">=26"
+  }
+}