@btst/stack 3.0.0-rc.2 → 3.0.0-rc.3

package/src/plugins/comments/api/getters.ts

@@ -15,7 +15,7 @@ import type {
  * Resolve display info for a batch of authorIds using the consumer-supplied resolveUser hook.
  * Deduplicates lookups — each unique authorId is resolved only once per call.
  *
- * @remarks **Security:** No authorization hooks are called. The caller is responsible for
+ * @remarks **Security:** Operation authorization and lifecycle hooks are not called. The caller is responsible for
  * any access-control checks before invoking this function.
  */
 async function resolveAuthors(
@@ -395,7 +395,23 @@ export async function getCommentById(
 	});
 
 	if (!comment) return null;
+	return enrichCommentRecord(adapter, comment, resolveUser, currentUserId);
+}
 
+/**
+ * Enrich an already-read comment record without reloading its domain fields.
+ *
+ * This preserves the exact snapshot returned by an atomic mutation while
+ * resolving presentation-only author and current-user like metadata.
+ */
+export async function enrichCommentRecord(
+	adapter: Adapter,
+	comment: Comment,
+	resolveUser?: (
+		authorId: string,
+	) => Promise<{ name: string; avatarUrl?: string } | null>,
+	currentUserId?: string,
+): Promise<SerializedComment> {
 	const authorMap = await resolveAuthors([comment.authorId], resolveUser);
 
 	const likedCommentIds = new Set<string>();
@@ -403,11 +419,11 @@ export async function getCommentById(
 		const like = await adapter.findOne<CommentLike>({
 			model: "commentLike",
 			where: [
-				{ field: "commentId", value: id, operator: "eq" },
+				{ field: "commentId", value: comment.id, operator: "eq" },
 				{ field: "authorId", value: currentUserId, operator: "eq" },
 			],
 		});
-		if (like) likedCommentIds.add(id);
+		if (like) likedCommentIds.add(comment.id);
 	}
 
 	return enrichComment(comment, authorMap, likedCommentIds);

package/src/plugins/comments/api/index.ts

@@ -1,9 +1,4 @@
-export {
-	commentsBackendPlugin,
-	type CommentsApiRouter,
-	type CommentsApiContext,
-	type CommentsBackendOptions,
-} from "./plugin";
+export * from "./plugin";
 export {
 	listComments,
 	getCommentById,
@@ -19,3 +14,4 @@ export {
 } from "./mutations";
 export { serializeComment } from "./serializers";
 export { COMMENTS_QUERY_KEYS } from "./query-key-defs";
+export { commentsPermissions } from "../permissions";

package/src/plugins/comments/api/lifecycle-migrations.ts

@@ -0,0 +1,20 @@
+/**
+ * Removed Comments lifecycle names and their canonical v3 replacements.
+ *
+ * Approval remains a meaningful moderation event rather than being flattened
+ * into a generic update callback.
+ */
+export const COMMENTS_LIFECYCLE_HOOK_MIGRATIONS = Object.freeze({
+	onBeforeList: "onBeforeListComments",
+	onBeforeCount: "onBeforeCountComments",
+	onBeforeListByAuthor: "onBeforeListCommentsByAuthor",
+	onBeforePost: "onBeforeCreateComment",
+	onAfterPost: "onAfterCreateComment",
+	onBeforeEdit: "onBeforeUpdateComment",
+	onAfterEdit: "onAfterUpdateComment",
+	onBeforeLike: "onBeforeToggleCommentReaction",
+	onBeforeStatusChange: "onBeforeModerateComment",
+	onAfterApprove: "onAfterApproveComment",
+	onBeforeDelete: "onBeforeDeleteComment",
+	onAfterDelete: "onAfterDeleteComment",
+} as const);

package/src/plugins/comments/api/mutations.ts

@@ -1,6 +1,80 @@
 import type { DBAdapter as Adapter } from "@btst/db";
 import type { Comment, CommentLike } from "../types";
 
+class StaleCommentStateError extends Error {}
+
+const AFFECTED_ROW_KEYS = [
+	"rowCount",
+	"affectedRows",
+	"rowsAffected",
+	"changes",
+	"numUpdatedRows",
+] as const;
+
+/**
+ * Normalize the affected-row shapes returned by supported DBAdapter runtimes.
+ *
+ * The declared adapter contract is a number, while some pinned adapters return
+ * driver results and the memory adapter returns the updated row. Unknown
+ * shapes fail closed rather than turning a zero-row CAS into a successful one.
+ */
+function hasPositiveCount(value: unknown): boolean {
+	if (typeof value === "number") return Number.isFinite(value) && value > 0;
+	if (typeof value === "bigint") return value > 0n;
+	return false;
+}
+
+function isMemoryCommentRow(
+	result: Record<string, unknown>,
+	expectedId: string,
+): boolean {
+	return (
+		result.id === expectedId &&
+		typeof result.resourceId === "string" &&
+		typeof result.resourceType === "string" &&
+		typeof result.authorId === "string" &&
+		typeof result.body === "string" &&
+		(result.status === "pending" ||
+			result.status === "approved" ||
+			result.status === "spam") &&
+		typeof result.likes === "number" &&
+		result.createdAt instanceof Date &&
+		result.updatedAt instanceof Date
+	);
+}
+
+function didUpdateRows(result: unknown, expectedId: string): boolean {
+	if (typeof result === "number" || typeof result === "bigint") {
+		return hasPositiveCount(result);
+	}
+	if (!result || typeof result !== "object") return false;
+
+	const record = result as Record<string, unknown>;
+	// Postgres.js and Bun SQL attach a scalar count to their result array.
+	if ("count" in record) return hasPositiveCount(record.count);
+	// MySQL driver results are tuples whose affected-row header is element 0.
+	// Later tuple entries are metadata and must never turn a zero count into a
+	// successful authorization CAS.
+	if (Array.isArray(result)) {
+		return result.length > 0 && didUpdateRows(result[0], expectedId);
+	}
+
+	for (const key of AFFECTED_ROW_KEYS) {
+		if (key in record) return hasPositiveCount(record[key]);
+	}
+	// Cloudflare D1 exposes the affected-row count at meta.changes.
+	if ("meta" in record) {
+		const meta = record.meta;
+		return Boolean(
+			meta &&
+				typeof meta === "object" &&
+				"changes" in meta &&
+				hasPositiveCount((meta as Record<string, unknown>).changes),
+		);
+	}
+	return isMemoryCommentRow(record, expectedId);
+}
+
 /**
  * Input for creating a new comment.
  */
@@ -16,9 +90,9 @@ export interface CreateCommentInput {
 /**
  * Create a new comment.
  *
- * @remarks **Security:** No authorization hooks are called. The caller is
- * responsible for any access-control checks (e.g., onBeforePost) before
- * invoking this function.
+ * @remarks **Security:** Operation authorization and lifecycle hooks are not called. The caller is
+ * responsible for authorization and lifecycle composition before invoking
+ * this lower-level data function.
  */
 export async function createComment(
 	adapter: Adapter,
@@ -43,52 +117,102 @@ export async function createComment(
 /**
  * Update the body of an existing comment and set editedAt.
  *
- * @remarks **Security:** No authorization hooks are called. The caller is
- * responsible for ensuring the requesting user owns the comment (onBeforeEdit).
+ * @remarks **Security:** Operation authorization and lifecycle hooks are not called. The caller is
+ * responsible for authorization and lifecycle composition. Pass the complete
+ * authorized `expected` snapshot to make the edit conditional and construct
+ * the result without a racy post-write read.
  */
 export async function updateComment(
 	adapter: Adapter,
 	id: string,
 	body: string,
+	expected?: Comment,
 ): Promise<Comment | null> {
-	const existing = await adapter.findOne<Comment>({
-		model: "comment",
-		where: [{ field: "id", value: id, operator: "eq" }],
-	});
-	if (!existing) return null;
+	const editedAt = new Date();
+	const update = {
+		body,
+		editedAt,
+		updatedAt: editedAt,
+	};
+	if (!expected) {
+		return adapter.update<Comment>({
+			model: "comment",
+			where: [{ field: "id", value: id, operator: "eq" }],
+			update,
+		});
+	}
+	if (expected.id !== id) return null;
 
-	return adapter.update<Comment>({
+	const matched = await adapter.updateMany({
 		model: "comment",
-		where: [{ field: "id", value: id, operator: "eq" }],
-		update: {
-			body,
-			editedAt: new Date(),
-			updatedAt: new Date(),
-		},
+		where: [
+			{ field: "id", value: id, operator: "eq" },
+			{ field: "authorId", value: expected.authorId, operator: "eq" },
+			{ field: "body", value: expected.body, operator: "eq" },
+			{ field: "status", value: expected.status, operator: "eq" },
+			{ field: "likes", value: expected.likes, operator: "eq" },
+			{ field: "updatedAt", value: expected.updatedAt, operator: "eq" },
+		],
+		update,
 	});
+	return didUpdateRows(matched, id) ? { ...expected, ...update } : null;
 }
 
 /**
  * Update the status of a comment (approve, reject, spam).
  *
- * @remarks **Security:** No authorization hooks are called. Callers should
- * ensure the requesting user has moderation privileges.
+ * @remarks **Security:** Operation authorization and lifecycle hooks are not called. Callers should
+ * authorize moderation before calling this lower-level data function. Pass the
+ * complete authorized `expected` snapshot to make the transition conditional,
+ * fail closed on concurrent changes, and avoid a racy post-write read.
  */
 export async function updateCommentStatus(
 	adapter: Adapter,
 	id: string,
 	status: "pending" | "approved" | "spam",
+	expected?: Comment,
 ): Promise<Comment | null> {
-	const existing = await adapter.findOne<Comment>({
+	const updatedAt = new Date();
+	const update = { status, updatedAt };
+	if (!expected) {
+		return adapter.update<Comment>({
+			model: "comment",
+			where: [{ field: "id", value: id, operator: "eq" }],
+			update,
+		});
+	}
+	if (expected.id !== id) return null;
+
+	const matched = await adapter.updateMany({
 		model: "comment",
-		where: [{ field: "id", value: id, operator: "eq" }],
+		where: [
+			{ field: "id", value: id, operator: "eq" },
+			{ field: "resourceId", value: expected.resourceId, operator: "eq" },
+			{ field: "resourceType", value: expected.resourceType, operator: "eq" },
+			{ field: "authorId", value: expected.authorId, operator: "eq" },
+			{ field: "body", value: expected.body, operator: "eq" },
+			{ field: "status", value: expected.status, operator: "eq" },
+			{ field: "likes", value: expected.likes, operator: "eq" },
+			{ field: "updatedAt", value: expected.updatedAt, operator: "eq" },
+		],
+		update,
 	});
-	if (!existing) return null;
+	return didUpdateRows(matched, id) ? { ...expected, ...update } : null;
+}
 
-	return adapter.update<Comment>({
+async function deleteCommentTree(
+	adapter: Pick<Adapter, "delete">,
+	id: string,
+): Promise<void> {
+	// Remove child replies first so they don't become orphans. Their
+	// commentLike rows are cleaned up by the FK cascade on commentLike.commentId.
+	await adapter.delete({
+		model: "comment",
+		where: [{ field: "parentId", value: id, operator: "eq" }],
+	});
+	await adapter.delete({
 		model: "comment",
 		where: [{ field: "id", value: id, operator: "eq" }],
-		update: { status, updatedAt: new Date() },
 	});
 }
 
@@ -103,33 +227,37 @@ export async function updateCommentStatus(
  * Comments are only one level deep (the UI prevents replying to replies), so a
  * single-level cascade is sufficient — no recursive walk is needed.
  *
- * @remarks **Security:** No authorization hooks are called. Callers should
- * ensure the requesting user has permission to delete this comment.
+ * @remarks **Security:** Operation authorization and lifecycle hooks are not called. Callers should
+ * ensure the requesting user has permission to delete this comment. Pass the
+ * authorized `expected` ownership to make deletion conditional.
  */
 export async function deleteComment(
 	adapter: Adapter,
 	id: string,
+	expected?: Pick<Comment, "authorId">,
 ): Promise<boolean> {
+	if (expected) {
+		return adapter.transaction(async (tx) => {
+			const matched = await tx.updateMany({
+				model: "comment",
+				where: [
+					{ field: "id", value: id, operator: "eq" },
+					{ field: "authorId", value: expected.authorId, operator: "eq" },
+				],
+				update: { updatedAt: new Date() },
+			});
+			if (!didUpdateRows(matched, id)) return false;
+			await deleteCommentTree(tx, id);
+			return true;
+		});
+	}
+
 	const existing = await adapter.findOne<Comment>({
 		model: "comment",
 		where: [{ field: "id", value: id, operator: "eq" }],
 	});
 	if (!existing) return false;
-
-	await adapter.transaction(async (tx) => {
-		// Remove child replies first so they don't become orphans.
-		// Their commentLike rows are cleaned up by the FK cascade on commentLike.commentId.
-		await tx.delete({
-			model: "comment",
-			where: [{ field: "parentId", value: id, operator: "eq" }],
-		});
-
-		// Remove the comment itself (its commentLike rows cascade via FK).
-		await tx.delete({
-			model: "comment",
-			where: [{ field: "id", value: id, operator: "eq" }],
-		});
-	});
+	await adapter.transaction((tx) => deleteCommentTree(tx, id));
 	return true;
 }
 
@@ -142,65 +270,110 @@ export async function deleteComment(
  * All reads and writes are performed inside a single transaction to prevent
  * concurrent requests from causing counter drift or duplicate like rows.
  *
- * @remarks **Security:** No authorization hooks are called. The caller is
- * responsible for ensuring the requesting user is authenticated (authorId is valid).
+ * @remarks **Security:** Operation authorization and lifecycle hooks are not called. The caller is
+ * responsible for ensuring the requesting user is authenticated (authorId is
+ * valid). Pass the authorized `expected` status to fail closed if visibility
+ * changes before the reaction is committed.
  */
+export function toggleCommentLike(
+	adapter: Adapter,
+	commentId: string,
+	authorId: string,
+): Promise<{ likes: number; isLiked: boolean }>;
+export function toggleCommentLike(
+	adapter: Adapter,
+	commentId: string,
+	authorId: string,
+	expected: Pick<Comment, "status">,
+): Promise<{ likes: number; isLiked: boolean } | null>;
 export async function toggleCommentLike(
 	adapter: Adapter,
 	commentId: string,
 	authorId: string,
-): Promise<{ likes: number; isLiked: boolean }> {
-	return adapter.transaction(async (tx) => {
-		const comment = await tx.findOne<Comment>({
-			model: "comment",
-			where: [{ field: "id", value: commentId, operator: "eq" }],
-		});
-		if (!comment) {
-			throw new Error("Comment not found");
-		}
-
-		const existingLike = await tx.findOne<CommentLike>({
-			model: "commentLike",
-			where: [
-				{ field: "commentId", value: commentId, operator: "eq" },
-				{ field: "authorId", value: authorId, operator: "eq" },
-			],
-		});
-
-		let newLikes: number;
-		let isLiked: boolean;
+	expected?: Pick<Comment, "status">,
+): Promise<{ likes: number; isLiked: boolean } | null> {
+	try {
+		return await adapter.transaction(async (tx) => {
+			const comment = await tx.findOne<Comment>({
+				model: "comment",
+				where: [
+					{ field: "id", value: commentId, operator: "eq" },
+					...(expected
+						? [
+								{
+									field: "status",
+									value: expected.status,
+									operator: "eq" as const,
+								},
+							]
+						: []),
+				],
+			});
+			if (!comment) {
+				if (expected) return null;
+				throw new Error("Comment not found");
+			}
 
-		if (existingLike) {
-			// Unlike
-			await tx.delete({
+			const existingLike = await tx.findOne<CommentLike>({
 				model: "commentLike",
 				where: [
 					{ field: "commentId", value: commentId, operator: "eq" },
 					{ field: "authorId", value: authorId, operator: "eq" },
 				],
 			});
-			newLikes = Math.max(0, comment.likes - 1);
-			isLiked = false;
-		} else {
-			// Like
-			await tx.create<CommentLike>({
-				model: "commentLike",
-				data: {
-					commentId,
-					authorId,
-					createdAt: new Date(),
-				},
-			});
-			newLikes = comment.likes + 1;
-			isLiked = true;
-		}
 
-		await tx.update<Comment>({
-			model: "comment",
-			where: [{ field: "id", value: commentId, operator: "eq" }],
-			update: { likes: newLikes, updatedAt: new Date() },
-		});
+			let newLikes: number;
+			let isLiked: boolean;
 
-		return { likes: newLikes, isLiked };
-	});
+			if (existingLike) {
+				// Unlike
+				await tx.delete({
+					model: "commentLike",
+					where: [
+						{ field: "commentId", value: commentId, operator: "eq" },
+						{ field: "authorId", value: authorId, operator: "eq" },
+					],
+				});
+				newLikes = Math.max(0, comment.likes - 1);
+				isLiked = false;
+			} else {
+				// Like
+				await tx.create<CommentLike>({
+					model: "commentLike",
+					data: {
+						commentId,
+						authorId,
+						createdAt: new Date(),
+					},
+				});
+				newLikes = comment.likes + 1;
+				isLiked = true;
+			}
+
+			if (expected) {
+				const updated = await tx.updateMany({
+					model: "comment",
+					where: [
+						{ field: "id", value: commentId, operator: "eq" },
+						{ field: "status", value: expected.status, operator: "eq" },
+					],
+					update: { likes: newLikes, updatedAt: new Date() },
+				});
+				if (!didUpdateRows(updated, commentId)) {
+					throw new StaleCommentStateError();
+				}
+			} else {
+				await tx.update<Comment>({
+					model: "comment",
+					where: [{ field: "id", value: commentId, operator: "eq" }],
+					update: { likes: newLikes, updatedAt: new Date() },
+				});
+			}
+
+			return { likes: newLikes, isLiked };
+		});
+	} catch (error) {
+		if (error instanceof StaleCommentStateError) return null;
+		throw error;
+	}
 }