convex-feedback 0.2.0-beta.8 → 0.2.0

package/src/component/roadmap.ts

@@ -2,8 +2,9 @@ import { paginator } from "convex-helpers/server/pagination";
 import {
   paginationOptsValidator,
   paginationResultValidator,
+  type PaginationResult,
 } from "convex/server";
-import { ConvexError, v } from "convex/values";
+import { ConvexError, v, type Infer } from "convex/values";
 
 import { internal } from "./_generated/api.js";
 import type { Id } from "./_generated/dataModel.js";
@@ -28,8 +29,35 @@ const POSITION_STEP = 1_000_000;
 const REBALANCE_GAP_THRESHOLD = 10;
 const rebalanceBatchSize = 100;
 const deletionBatchSize = 100;
+const roadmapStatuses = ["planned", "in_progress", "shipped"] as const;
 
 type RebalanceCtx = MutationCtx | QueryCtx;
+type RoadmapDatabase = ReturnType<typeof paginator<typeof schema>>;
+type RoadmapPaginationOpts = Infer<typeof paginationOptsValidator>;
+type RoadmapItemPage = PaginationResult<
+  ReturnType<typeof serializeRoadmapItem>
+>;
+
+type RoadmapListStreamState = {
+  cursor: string | null;
+  offset: number;
+  done: boolean;
+  generation: string | null;
+};
+
+type RoadmapListCursor = {
+  version: 1;
+  streams: RoadmapListStreamState[];
+};
+
+type RoadmapStatusPage = RoadmapItemPage & {
+  generation: string | null;
+};
+
+type RoadmapPageStream = {
+  stream: RoadmapListStreamState;
+  result: RoadmapStatusPage;
+};
 
 type RoadmapCreateArgs = {
   title: string;
@@ -123,6 +151,317 @@ async function scheduleRebalance(
   });
 }
 
+function newRoadmapListStreamState(
+  generation: string | null = null,
+): RoadmapListStreamState {
+  return { cursor: null, offset: 0, done: false, generation };
+}
+
+function initialRoadmapListCursor(): RoadmapListCursor {
+  return {
+    version: 1,
+    streams: roadmapStatuses.map(() => newRoadmapListStreamState()),
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isRoadmapListStreamState(
+  value: unknown,
+): value is RoadmapListStreamState {
+  if (!isRecord(value)) return false;
+  return (
+    (value.cursor === null || typeof value.cursor === "string") &&
+    typeof value.offset === "number" &&
+    Number.isInteger(value.offset) &&
+    value.offset >= 0 &&
+    typeof value.done === "boolean" &&
+    (value.generation === null || typeof value.generation === "string")
+  );
+}
+
+function decodeRoadmapListCursor(cursor: string | null): RoadmapListCursor {
+  if (cursor === null) return initialRoadmapListCursor();
+
+  let value: unknown;
+  try {
+    value = JSON.parse(cursor) as unknown;
+  } catch {
+    throw new ConvexError("InvalidCursor");
+  }
+
+  if (
+    !isRecord(value) ||
+    value.version !== 1 ||
+    !Array.isArray(value.streams) ||
+    value.streams.length !== roadmapStatuses.length ||
+    !value.streams.every(isRoadmapListStreamState)
+  ) {
+    throw new ConvexError("InvalidCursor");
+  }
+
+  return {
+    version: 1,
+    streams: value.streams.map((stream) => ({ ...stream })),
+  };
+}
+
+function encodeRoadmapListCursor(cursor: RoadmapListCursor): string {
+  return JSON.stringify(cursor);
+}
+
+async function paginateRoadmapStatus(
+  ctx: QueryCtx,
+  db: RoadmapDatabase,
+  status: RoadmapStatus,
+  paginationOpts: RoadmapPaginationOpts,
+): Promise<RoadmapStatusPage> {
+  const state = await getRebalanceState(ctx, status);
+  const generation = state?.visibleGeneration ?? null;
+  const roadmapQuery =
+    generation === null
+      ? db
+          .query("roadmap")
+          .withIndex("by_status_deleting_at_position", (q) =>
+            q.eq("status", status).eq("deletingAt", undefined),
+          )
+      : db
+          .query("roadmap")
+          .withIndex("by_status_deleting_at_rebalance_id_position", (q) =>
+            q
+              .eq("status", status)
+              .eq("deletingAt", undefined)
+              .eq("rebalanceId", generation),
+          );
+  const result = await roadmapQuery.paginate(paginationOpts);
+
+  return {
+    ...result,
+    generation,
+    page: result.page.map((item) =>
+      serializeRoadmapItem(
+        item,
+        generation === null ? undefined : item.rebalancePosition,
+      ),
+    ),
+  };
+}
+
+function compareRoadmapItems(
+  left: RoadmapItemPage["page"][number],
+  right: RoadmapItemPage["page"][number],
+): number {
+  if (left.position !== right.position) {
+    return left.position - right.position;
+  }
+  if (left.creationTime !== right.creationTime) {
+    return left.creationTime - right.creationTime;
+  }
+  return left.id < right.id ? -1 : left.id > right.id ? 1 : 0;
+}
+
+function mergeRoadmapPages(
+  pages: Array<RoadmapPageStream | null>,
+  offsets: number[],
+  limit: number,
+) {
+  const page: RoadmapItemPage["page"] = [];
+
+  while (page.length < limit) {
+    let selectedIndex = -1;
+    for (const [index, value] of pages.entries()) {
+      if (value === null) continue;
+      const item = value.result.page[offsets[index]!];
+      if (item === undefined) continue;
+      const selected =
+        selectedIndex < 0
+          ? undefined
+          : pages[selectedIndex]!.result.page[offsets[selectedIndex]!];
+      if (selected === undefined || compareRoadmapItems(item, selected) < 0) {
+        selectedIndex = index;
+      }
+    }
+    if (selectedIndex < 0) break;
+    page.push(pages[selectedIndex]!.result.page[offsets[selectedIndex]!]!);
+    offsets[selectedIndex]! += 1;
+  }
+
+  return page;
+}
+
+async function paginateUnfilteredRoadmapRange(
+  ctx: QueryCtx,
+  db: RoadmapDatabase,
+  paginationOpts: RoadmapPaginationOpts,
+  startCursor: RoadmapListCursor,
+  endCursor: RoadmapListCursor,
+): Promise<RoadmapItemPage> {
+  const generations = await Promise.all(
+    roadmapStatuses.map(async (status) => {
+      const state = await getRebalanceState(ctx, status);
+      return state?.visibleGeneration ?? null;
+    }),
+  );
+  if (
+    startCursor.streams.some(
+      (stream, index) =>
+        stream.generation !== generations[index] ||
+        endCursor.streams[index]!.generation !== generations[index],
+    )
+  ) {
+    throw new ConvexError("InvalidCursor");
+  }
+
+  const pages = await Promise.all(
+    roadmapStatuses.map(async (status, index) => {
+      const start = startCursor.streams[index]!;
+      const end = endCursor.streams[index]!;
+      if (start.generation !== end.generation) {
+        throw new ConvexError("InvalidCursor");
+      }
+      if (start.done) return null;
+
+      if (start.cursor === end.cursor) {
+        if (end.offset <= start.offset) return null;
+        const result = await paginateRoadmapStatus(ctx, db, status, {
+          cursor: start.cursor,
+          numItems: end.offset,
+        });
+        return { stream: start, result };
+      }
+
+      if (end.cursor === null) {
+        throw new ConvexError("InvalidCursor");
+      }
+      const result = await paginateRoadmapStatus(ctx, db, status, {
+        cursor: start.cursor,
+        endCursor: end.cursor,
+        numItems: paginationOpts.numItems,
+      });
+      return { stream: start, result };
+    }),
+  );
+  const offsets = pages.map((page) => page?.stream.offset ?? 0);
+
+  return {
+    page: mergeRoadmapPages(pages, offsets, Number.POSITIVE_INFINITY),
+    isDone: endCursor.streams.every((stream) => stream.done),
+    continueCursor: encodeRoadmapListCursor(endCursor),
+  };
+}
+
+/**
+ * Unfiltered reads merge one stable stream per status. Each stream is pinned
+ * to the generation visible in the query snapshot, so promotion batches can
+ * never leak a mixture of live and replacement positions.
+ */
+async function paginateUnfilteredRoadmap(
+  ctx: QueryCtx,
+  db: RoadmapDatabase,
+  paginationOpts: RoadmapPaginationOpts,
+): Promise<RoadmapItemPage> {
+  const cursor = decodeRoadmapListCursor(paginationOpts.cursor);
+  if (
+    paginationOpts.endCursor !== undefined &&
+    paginationOpts.endCursor !== null
+  ) {
+    return await paginateUnfilteredRoadmapRange(
+      ctx,
+      db,
+      paginationOpts,
+      cursor,
+      decodeRoadmapListCursor(paginationOpts.endCursor),
+    );
+  }
+  const generations = await Promise.all(
+    roadmapStatuses.map(async (status) => {
+      const state = await getRebalanceState(ctx, status);
+      return state?.visibleGeneration ?? null;
+    }),
+  );
+  const streams = cursor.streams.map((stream, index) =>
+    stream.generation === generations[index]
+      ? stream
+      : newRoadmapListStreamState(generations[index]),
+  );
+  const pages = await Promise.all(
+    roadmapStatuses.map(async (status, index) => {
+      const stream = streams[index]!;
+      if (stream.done) return null;
+
+      const result = await paginateRoadmapStatus(ctx, db, status, {
+        ...paginationOpts,
+        cursor: stream.cursor,
+        endCursor: undefined,
+        numItems: Math.max(
+          paginationOpts.numItems,
+          stream.offset + paginationOpts.numItems,
+        ),
+      });
+
+      return { stream, result };
+    }),
+  );
+  const nextStreams = streams.map((stream) => ({ ...stream }));
+  const offsets = pages.map((page) => page?.stream.offset ?? 0);
+  const page = mergeRoadmapPages(pages, offsets, paginationOpts.numItems);
+
+  for (const [index, value] of pages.entries()) {
+    if (value === null) continue;
+    const stream = nextStreams[index]!;
+    const result = value.result;
+    const consumed = offsets[index]! - value.stream.offset;
+    const pageExhausted = offsets[index]! >= result.page.length;
+    stream.generation = result.generation;
+    if (pageExhausted) {
+      stream.done = result.isDone;
+      if (result.isDone) {
+        // Keep the source page boundary even when the paginator uses "[]" as
+        // its terminal cursor, so a bound previous-page query can reproduce
+        // exactly the same range.
+        stream.cursor = value.stream.cursor;
+        stream.offset = result.page.length;
+      } else {
+        stream.cursor = result.continueCursor;
+        stream.offset = 0;
+      }
+    } else {
+      stream.done = false;
+      stream.cursor = value.stream.cursor;
+      stream.offset = value.stream.offset + consumed;
+    }
+  }
+
+  const nextCursor: RoadmapListCursor = {
+    version: 1,
+    streams: nextStreams,
+  };
+  return {
+    page,
+    isDone: nextStreams.every((stream) => stream.done),
+    continueCursor: encodeRoadmapListCursor(nextCursor),
+  };
+}
+
+export const get = query({
+  args: { roadmapId: v.id("roadmap") },
+  returns: v.union(roadmapItemValidator, v.null()),
+  handler: async (ctx, args) => {
+    const item = await ctx.db.get("roadmap", args.roadmapId);
+    if (item === null || item.deletingAt !== undefined) return null;
+
+    const state = await getRebalanceState(ctx, item.status);
+    return serializeRoadmapItem(
+      item,
+      state?.visibleGeneration === undefined
+        ? undefined
+        : item.rebalancePosition,
+    );
+  },
+});
+
 export const list = query({
   args: {
     paginationOpts: paginationOptsValidator,
@@ -132,40 +471,19 @@ export const list = query({
   handler: async (ctx, args) => {
     const db = paginator(ctx.db, schema);
     const status = args.status;
-    const state =
-      status === undefined ? null : await getRebalanceState(ctx, status);
-    const visibleGeneration = state?.visibleGeneration;
-    const roadmapQuery =
-      status !== undefined && visibleGeneration !== undefined
-        ? db
-            .query("roadmap")
-            .withIndex("by_status_deleting_at_rebalance_id_position", (q) =>
-              q
-                .eq("status", status)
-                .eq("deletingAt", undefined)
-                .eq("rebalanceId", visibleGeneration),
-            )
-        : status === undefined
-          ? db
-              .query("roadmap")
-              .withIndex("by_deleting_at_and_position", (q) =>
-                q.eq("deletingAt", undefined),
-              )
-          : db
-              .query("roadmap")
-              .withIndex("by_status_deleting_at_position", (q) =>
-                q.eq("status", status).eq("deletingAt", undefined),
-              );
-    const result = await roadmapQuery.paginate(args.paginationOpts);
-    return {
-      ...result,
-      page: result.page.map((item) =>
-        serializeRoadmapItem(
-          item,
-          visibleGeneration === undefined ? undefined : item.rebalancePosition,
-        ),
-      ),
-    };
+    if (status === undefined) {
+      return await paginateUnfilteredRoadmap(ctx, db, args.paginationOpts);
+    }
+
+    const result = await paginateRoadmapStatus(
+      ctx,
+      db,
+      status,
+      args.paginationOpts,
+    );
+    const { generation: _generation, ...publicResult } = result;
+    void _generation;
+    return publicResult;
   },
 });
 
@@ -530,6 +848,9 @@ async function attachFeedbackRecord(
     throw new ConvexError("Roadmap item is being deleted.");
   }
   if (entry === null) throw new ConvexError("Entry not found.");
+  if (entry.deletingAt !== undefined) {
+    throw new ConvexError("Entry is being deleted.");
+  }
   if (entry.roadmapId === roadmapId) return;
 
   const now = Date.now();
@@ -619,6 +940,7 @@ export const listFeedback = query({
       .query("entries")
       .withIndex("by_roadmap_id", (q) => q.eq("roadmapId", args.roadmapId))
       .order("desc")
+      .filterWith((entry) => Promise.resolve(entry.deletingAt === undefined))
       .paginate(args.paginationOpts);
     return {
       ...result,

package/src/component/schema.ts

@@ -26,7 +26,10 @@ const schema = defineSchema({
     metadata: v.optional(feedbackMetadataValidator),
     priority: v.optional(entryPriorityValidator),
     roadmapId: v.optional(v.id("roadmap")),
+    /** Set while dependent comments and reactions are being removed. */
+    deletingAt: v.optional(v.number()),
   })
+    .index("by_actor", ["actorId"])
     .index("by_kind", ["kind"])
     .index("by_status", ["status"])
     .index("by_kind_status", ["kind", "status"])
@@ -48,7 +51,13 @@ const schema = defineSchema({
     .index("by_roadmap_id", ["roadmapId"])
     .searchIndex("search", {
       searchField: "searchText",
-      filterFields: ["kind", "status", "statusFilter", "priority"],
+      filterFields: [
+        "kind",
+        "status",
+        "statusFilter",
+        "priority",
+        "deletingAt",
+      ],
     }),
 
   roadmap: defineTable({
@@ -104,22 +113,49 @@ const schema = defineSchema({
     likeCount: v.number(),
     replyCount: v.number(),
     updatedAt: v.optional(v.number()),
+    /**
+     * Legacy compatibility field. New comment deletion uses deletingAt and
+     * permanently removes the subtree; this field is drained by the legacy
+     * cleanup migration and is not part of any public type.
+     */
     deletedAt: v.optional(v.number()),
+    /** Internal one-time marker used by the bounded legacy orphan sweep. */
+    legacyCleanupAt: v.optional(v.number()),
+    /** Timestamp while this comment subtree is being removed. */
+    deletingAt: v.optional(v.number()),
+    /** Root comment owning the pending subtree cleanup. */
+    deletionRootId: v.optional(v.id("comments")),
   })
+    .index("by_actor", ["actorId"])
     .index("by_entry_parent", ["entryId", "parentCommentId"])
-    .index("by_entry_parent_likes", [
+    .index("by_entry_parent_deleting", [
+      "entryId",
+      "parentCommentId",
+      "deletingAt",
+      "deletedAt",
+    ])
+    .index("by_entry_parent_deleting_likes", [
       "entryId",
       "parentCommentId",
+      "deletingAt",
+      "deletedAt",
       "likeCount",
-    ]),
+    ])
+    .index("by_deleted_at", ["deletedAt"])
+    .index("by_legacy_cleanup", ["legacyCleanupAt"])
+    .index("by_entry_deletion_root", ["entryId", "deletionRootId"]),
 
   reactions: defineTable({
     actorId: v.string(),
     entryId: v.optional(v.id("entries")),
     commentId: v.optional(v.id("comments")),
+    /** Internal one-time marker used by the bounded legacy orphan sweep. */
+    legacyCleanupAt: v.optional(v.number()),
   })
+    .index("by_actor", ["actorId"])
     .index("by_entry_actor", ["entryId", "actorId"])
-    .index("by_comment_actor", ["commentId", "actorId"]),
+    .index("by_comment_actor", ["commentId", "actorId"])
+    .index("by_legacy_cleanup", ["legacyCleanupAt"]),
 });
 
 export default schema;

package/src/react/README.md

@@ -5,3 +5,8 @@
 The hooks expose public entries, search/similarity, lazy direct-child comment pagination, mutations, admin inbox queries, and roadmap operations. 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.
+
+Lifecycle callbacks are server-side options on `exposeFeedbackApi`; hooks only
+consume the generated host API and do not configure callbacks. See the
+[canonical callback reference](../../README.md#lifecycle-callbacks) for the
+host-side API and mutation result behavior.

package/src/react/index.ts

@@ -12,10 +12,22 @@ import type {
   EntrySort,
   EntryStatus,
   EntryStatusFilter,
+  RoadmapItem,
   RoadmapStatus,
   SimilarEntriesResult,
 } from "../component/model.js";
 
+function compareRoadmapItemsByPosition(
+  left: RoadmapItem,
+  right: RoadmapItem,
+): number {
+  if (left.position !== right.position) return left.position - right.position;
+  if (left.creationTime !== right.creationTime) {
+    return left.creationTime - right.creationTime;
+  }
+  return left.id.localeCompare(right.id);
+}
+
 /**
  * Client-side pagination defaults used by hooks created with
  * `createFeedbackHooks`.
@@ -150,6 +162,7 @@ export interface SearchEntriesArgs {
 export interface UseAdminEntriesArgs {
   kinds?: readonly EntryKind[];
   status?: EntryStatus;
+  statusFilter?: EntryStatusFilter;
   priority?: EntryPriority;
 }
 
@@ -308,6 +321,9 @@ function createFeedbackHooksImplementation<RateLimitResult>(
         {
           ...(args.kinds === undefined ? {} : { kinds: [...args.kinds] }),
           ...(args.status === undefined ? {} : { status: args.status }),
+          ...(args.statusFilter === undefined
+            ? {}
+            : { statusFilter: args.statusFilter }),
           ...(args.priority === undefined ? {} : { priority: args.priority }),
         },
         { initialNumItems: entryPageSize },
@@ -333,6 +349,9 @@ function createFeedbackHooksImplementation<RateLimitResult>(
               searchQuery,
               ...(args.kinds === undefined ? {} : { kinds: [...args.kinds] }),
               ...(args.status === undefined ? {} : { status: args.status }),
+              ...(args.statusFilter === undefined
+                ? {}
+                : { statusFilter: args.statusFilter }),
               ...(args.priority === undefined
                 ? {}
                 : { priority: args.priority }),
@@ -341,12 +360,76 @@ function createFeedbackHooksImplementation<RateLimitResult>(
       );
     },
 
+    /**
+     * An unfiltered roadmap is composed from one stream per status so a
+     * rebalance cannot mix live and replacement positions in the UI.
+     */
     useRoadmap(status?: RoadmapStatus) {
-      return usePaginatedQuery(
+      const planned = usePaginatedQuery(
         api.listRoadmap,
-        status === undefined ? {} : { status },
+        status === undefined || status === "planned"
+          ? { status: "planned" }
+          : "skip",
         { initialNumItems: roadmapPageSize },
       );
+      const inProgress = usePaginatedQuery(
+        api.listRoadmap,
+        status === undefined || status === "in_progress"
+          ? { status: "in_progress" }
+          : "skip",
+        { initialNumItems: roadmapPageSize },
+      );
+      const shipped = usePaginatedQuery(
+        api.listRoadmap,
+        status === undefined || status === "shipped"
+          ? { status: "shipped" }
+          : "skip",
+        { initialNumItems: roadmapPageSize },
+      );
+
+      if (status === "planned") return planned;
+      if (status === "in_progress") return inProgress;
+      if (status === "shipped") return shipped;
+
+      const roadmaps = [planned, inProgress, shipped];
+      const loadingFirstPage = roadmaps.some(
+        (roadmap) => roadmap.status === "LoadingFirstPage",
+      );
+      const loadingMore = roadmaps.some(
+        (roadmap) => roadmap.status === "LoadingMore",
+      );
+      const canLoadMore = roadmaps.some(
+        (roadmap) => roadmap.status === "CanLoadMore",
+      );
+
+      return {
+        results: roadmaps
+          .flatMap((roadmap) => roadmap.results)
+          .sort(compareRoadmapItemsByPosition),
+        status: loadingFirstPage
+          ? ("LoadingFirstPage" as const)
+          : loadingMore
+            ? ("LoadingMore" as const)
+            : canLoadMore
+              ? ("CanLoadMore" as const)
+              : ("Exhausted" as const),
+        isLoading: loadingFirstPage || loadingMore,
+        loadMore: (numItems: number) => {
+          for (const roadmap of roadmaps) {
+            if (roadmap.status === "CanLoadMore") {
+              roadmap.loadMore(numItems);
+            }
+          }
+        },
+      };
+    },
+
+    /** Reactively retrieves one roadmap item independently of the list page. */
+    useRoadmapItem(roadmapId: string | null | undefined) {
+      return useQuery(
+        api.getRoadmapItem,
+        roadmapId === null || roadmapId === undefined ? "skip" : { roadmapId },
+      );
     },
 
     useSearchRoadmap(searchQuery: string, limit = 10) {
@@ -412,6 +495,10 @@ function createFeedbackHooksImplementation<RateLimitResult>(
       return useMutation(api.updateEntry);
     },
 
+    useDeleteEntry() {
+      return useMutation(api.deleteEntry);
+    },
+
     /** Returns the bound status mutation. */
     useSetEntryStatus() {
       return useMutation(api.setEntryStatus);
@@ -464,7 +551,7 @@ function createFeedbackHooksImplementation<RateLimitResult>(
       return useMutation(api.updateComment);
     },
 
-    /** Returns the soft-delete-comment mutation. */
+    /** Returns the permanent comment-subtree deletion mutation. */
     useDeleteComment() {
       return useMutation(api.deleteComment);
     },