convex-feedback 0.1.0

package/src/component/helpers.ts

@@ -0,0 +1,105 @@
+import { ConvexError } from "convex/values";
+
+import type { DataModel } from "./_generated/dataModel.js";
+import type { QueryCtx } from "./types.js";
+import type { FeedbackComment, FeedbackEntry } from "./model.js";
+
+export function normalizeTitle(value: string): string {
+  return value.trim().replace(/\s+/g, " ").toLocaleLowerCase("en-US");
+}
+
+export function normalizeRequiredText(
+  value: string,
+  field: string,
+  maximumLength: number,
+): string {
+  const normalized = value.trim();
+  if (normalized.length === 0) {
+    throw new ConvexError(`${field} is required.`);
+  }
+  if (normalized.length > maximumLength) {
+    throw new ConvexError(
+      `${field} must be ${maximumLength} characters or fewer.`,
+    );
+  }
+  return normalized;
+}
+
+export function assertPositiveInteger(value: number, field: string): void {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new ConvexError(`${field} must be a positive integer.`);
+  }
+}
+
+export function assertActorId(actorId: string): void {
+  if (actorId.trim().length === 0) {
+    throw new ConvexError("Actor id must not be empty.");
+  }
+}
+
+export async function serializeEntry(
+  ctx: QueryCtx,
+  entry: DataModel["entries"]["document"],
+  viewerActorId: string | undefined,
+): Promise<FeedbackEntry> {
+  const reaction =
+    viewerActorId !== undefined
+      ? await ctx.db
+          .query("reactions")
+          .withIndex("by_entry_actor", (q) =>
+            q.eq("entryId", entry._id).eq("actorId", viewerActorId),
+          )
+          .unique()
+      : null;
+
+  return {
+    id: entry._id,
+    creationTime: entry._creationTime,
+    actorId: entry.actorId,
+    kind: entry.kind,
+    status: entry.status,
+    title: entry.title,
+    body: entry.body,
+    upvoteCount: entry.upvoteCount,
+    commentCount: entry.commentCount,
+    ...(entry.updatedAt === undefined ? {} : { updatedAt: entry.updatedAt }),
+    viewerHasUpvoted: reaction !== null,
+  };
+}
+
+export async function serializeComment(
+  ctx: QueryCtx,
+  comment: DataModel["comments"]["document"],
+  viewerActorId: string | undefined,
+): Promise<FeedbackComment> {
+  const reaction =
+    viewerActorId !== undefined
+      ? await ctx.db
+          .query("reactions")
+          .withIndex("by_comment_actor", (q) =>
+            q.eq("commentId", comment._id).eq("actorId", viewerActorId),
+          )
+          .unique()
+      : null;
+
+  return {
+    id: comment._id,
+    creationTime: comment._creationTime,
+    entryId: comment.entryId,
+    ...(comment.parentCommentId === undefined
+      ? {}
+      : { parentCommentId: comment.parentCommentId }),
+    actorId: comment.actorId,
+    depth: comment.depth,
+    body: comment.deletedAt === undefined ? comment.body : null,
+    likeCount: comment.likeCount,
+    replyCount: comment.replyCount,
+    ...(comment.updatedAt === undefined
+      ? {}
+      : { updatedAt: comment.updatedAt }),
+    ...(comment.deletedAt === undefined
+      ? {}
+      : { deletedAt: comment.deletedAt }),
+    viewerHasLiked: reaction !== null,
+  };
+}

package/src/component/model.ts

@@ -0,0 +1,76 @@
+import type { Infer } from "convex/values";
+import { v } from "convex/values";
+
+export const entryKindValidator = v.union(
+  v.literal("feedback"),
+  v.literal("feature_request"),
+  v.literal("bug_report"),
+);
+
+export const entryStatusValidator = v.union(
+  v.literal("open"),
+  v.literal("under_review"),
+  v.literal("planned"),
+  v.literal("in_progress"),
+  v.literal("completed"),
+  v.literal("closed"),
+);
+
+export const entrySortValidator = v.union(
+  v.literal("top"),
+  v.literal("newest"),
+);
+
+export const commentSortValidator = v.union(
+  v.literal("top"),
+  v.literal("newest"),
+  v.literal("oldest"),
+);
+
+export const actorValidator = v.object({
+  id: v.string(),
+  isModerator: v.boolean(),
+});
+
+export const publicEntryValidator = v.object({
+  id: v.string(),
+  creationTime: v.number(),
+  actorId: v.string(),
+  kind: entryKindValidator,
+  status: entryStatusValidator,
+  title: v.string(),
+  body: v.string(),
+  upvoteCount: v.number(),
+  commentCount: v.number(),
+  updatedAt: v.optional(v.number()),
+  viewerHasUpvoted: v.boolean(),
+});
+
+export const publicCommentValidator = v.object({
+  id: v.string(),
+  creationTime: v.number(),
+  entryId: v.string(),
+  parentCommentId: v.optional(v.string()),
+  actorId: v.string(),
+  depth: v.number(),
+  body: v.union(v.string(), v.null()),
+  likeCount: v.number(),
+  replyCount: v.number(),
+  updatedAt: v.optional(v.number()),
+  deletedAt: v.optional(v.number()),
+  viewerHasLiked: v.boolean(),
+});
+
+export const similarEntriesValidator = v.object({
+  exact: v.array(publicEntryValidator),
+  similar: v.array(publicEntryValidator),
+});
+
+export type EntryKind = Infer<typeof entryKindValidator>;
+export type EntryStatus = Infer<typeof entryStatusValidator>;
+export type EntrySort = Infer<typeof entrySortValidator>;
+export type CommentSort = Infer<typeof commentSortValidator>;
+export type FeedbackActor = Infer<typeof actorValidator>;
+export type FeedbackEntry = Infer<typeof publicEntryValidator>;
+export type FeedbackComment = Infer<typeof publicCommentValidator>;
+export type SimilarEntriesResult = Infer<typeof similarEntriesValidator>;

package/src/component/schema.ts

@@ -0,0 +1,60 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+import { entryKindValidator, entryStatusValidator } from "./model.js";
+
+const schema = defineSchema({
+  entries: defineTable({
+    actorId: v.string(),
+    kind: entryKindValidator,
+    status: entryStatusValidator,
+    title: v.string(),
+    body: v.string(),
+    normalizedTitle: v.string(),
+    searchText: v.string(),
+    upvoteCount: v.number(),
+    commentCount: v.number(),
+    updatedAt: v.optional(v.number()),
+  })
+    .index("by_kind", ["kind"])
+    .index("by_status", ["status"])
+    .index("by_kind_status", ["kind", "status"])
+    .index("by_upvotes", ["upvoteCount"])
+    .index("by_kind_upvotes", ["kind", "upvoteCount"])
+    .index("by_status_upvotes", ["status", "upvoteCount"])
+    .index("by_kind_status_upvotes", ["kind", "status", "upvoteCount"])
+    .index("by_normalized_title", ["normalizedTitle"])
+    .index("by_kind_normalized_title", ["kind", "normalizedTitle"])
+    .searchIndex("search", {
+      searchField: "searchText",
+      filterFields: ["kind", "status"],
+    }),
+
+  comments: defineTable({
+    entryId: v.id("entries"),
+    parentCommentId: v.optional(v.id("comments")),
+    actorId: v.string(),
+    depth: v.number(),
+    body: v.string(),
+    likeCount: v.number(),
+    replyCount: v.number(),
+    updatedAt: v.optional(v.number()),
+    deletedAt: v.optional(v.number()),
+  })
+    .index("by_entry_parent", ["entryId", "parentCommentId"])
+    .index("by_entry_parent_likes", [
+      "entryId",
+      "parentCommentId",
+      "likeCount",
+    ]),
+
+  reactions: defineTable({
+    actorId: v.string(),
+    entryId: v.optional(v.id("entries")),
+    commentId: v.optional(v.id("comments")),
+  })
+    .index("by_entry_actor", ["entryId", "actorId"])
+    .index("by_comment_actor", ["commentId", "actorId"]),
+});
+
+export default schema;

package/src/component/types.ts

@@ -0,0 +1,6 @@
+import type { GenericMutationCtx, GenericQueryCtx } from "convex/server";
+
+import type { DataModel } from "./_generated/dataModel.js";
+
+export type QueryCtx = GenericQueryCtx<DataModel>;
+export type MutationCtx = GenericMutationCtx<DataModel>;

package/src/react/README.md

@@ -0,0 +1,7 @@
+# React hooks layer
+
+`createFeedbackHooks(api, options?)` binds the host application's public Convex API to headless React hooks.
+
+The hooks expose entries, search/similarity, lazy direct-child comment pagination, mutations, and the configured client page sizes. Reply queries are not mounted by the hook layer automatically; the UI decides when a comment is expanded.
+
+Page-size defaults are client concerns. The server-side component still enforces its configured hard maximum. Keep the two aligned when overriding defaults.

package/src/react/index.ts

@@ -0,0 +1,140 @@
+"use client";
+
+import { usePaginatedQuery } from "convex-helpers/react";
+import { useMutation, useQuery } from "convex/react";
+
+import type { FeedbackPublicApi } from "../client/api.js";
+import type {
+  CommentSort,
+  EntryKind,
+  EntrySort,
+  EntryStatus,
+} from "../component/model.js";
+
+export interface FeedbackHooksOptions {
+  entryPageSize?: number;
+  commentPageSize?: number;
+  replyPageSize?: number;
+}
+
+export interface UseEntriesArgs {
+  kind?: EntryKind;
+  status?: EntryStatus;
+  sort?: EntrySort;
+}
+
+export interface UseCommentsArgs {
+  entryId: string;
+  parentCommentId?: string;
+  sort?: CommentSort;
+}
+
+export interface SearchEntriesArgs {
+  searchQuery: string;
+  kind?: EntryKind;
+  status?: EntryStatus;
+  limit?: number;
+}
+
+export interface SimilarEntriesArgs {
+  title: string;
+  body: string;
+  kind?: EntryKind;
+  limit?: number;
+}
+
+function positivePageSize(value: number | undefined, fallback: number): number {
+  return value !== undefined && Number.isInteger(value) && value > 0
+    ? value
+    : fallback;
+}
+
+export function createFeedbackHooks(
+  api: FeedbackPublicApi,
+  options: FeedbackHooksOptions = {},
+) {
+  const entryPageSize = positivePageSize(options.entryPageSize, 20);
+  const commentPageSize = positivePageSize(options.commentPageSize, 20);
+  const replyPageSize = positivePageSize(options.replyPageSize, 10);
+
+  return {
+    pageSizes: {
+      entries: entryPageSize,
+      comments: commentPageSize,
+      replies: replyPageSize,
+    } as const,
+
+    useEntries(args: UseEntriesArgs = {}) {
+      return usePaginatedQuery(api.listEntries, args, {
+        initialNumItems: entryPageSize,
+      });
+    },
+
+    useEntry(entryId: string | null | undefined) {
+      return useQuery(
+        api.getEntry,
+        entryId === null || entryId === undefined ? "skip" : { entryId },
+      );
+    },
+
+    useSearchEntries(args: SearchEntriesArgs) {
+      const searchQuery = args.searchQuery.trim();
+      const result = useQuery(
+        api.searchEntries,
+        searchQuery.length === 0 ? "skip" : { ...args, searchQuery },
+      );
+      return searchQuery.length === 0 ? [] : result;
+    },
+
+    useSimilarEntries(args: SimilarEntriesArgs) {
+      const shouldSkip =
+        args.title.trim().length === 0 && args.body.trim().length === 0;
+      const result = useQuery(
+        api.findSimilarEntries,
+        shouldSkip ? "skip" : args,
+      );
+      return shouldSkip ? { exact: [], similar: [] } : result;
+    },
+
+    useComments(args: UseCommentsArgs) {
+      return usePaginatedQuery(api.listComments, args, {
+        initialNumItems:
+          args.parentCommentId === undefined ? commentPageSize : replyPageSize,
+      });
+    },
+
+    useCreateEntry() {
+      return useMutation(api.createEntry);
+    },
+
+    useUpdateEntry() {
+      return useMutation(api.updateEntry);
+    },
+
+    useSetEntryStatus() {
+      return useMutation(api.setEntryStatus);
+    },
+
+    useSetEntryUpvote() {
+      return useMutation(api.setEntryUpvote);
+    },
+
+    useCreateComment() {
+      return useMutation(api.createComment);
+    },
+
+    useUpdateComment() {
+      return useMutation(api.updateComment);
+    },
+
+    useDeleteComment() {
+      return useMutation(api.deleteComment);
+    },
+
+    useSetCommentLike() {
+      return useMutation(api.setCommentLike);
+    },
+  };
+}
+
+export type FeedbackHooks = ReturnType<typeof createFeedbackHooks>;

package/src/test.ts

@@ -0,0 +1,18 @@
+/// <reference types="vite/client" />
+
+import type { TestConvex } from "convex-test";
+import type { GenericSchema, SchemaDefinition } from "convex/server";
+
+import schema from "./component/schema.js";
+
+const modules = import.meta.glob("./component/**/*.ts");
+
+export function register(
+  test: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
+  name = "feedback",
+): void {
+  test.registerComponent(name, schema, modules);
+}
+
+export { schema, modules };
+export default { register, schema, modules };