@vllnt/convex-reactions 0.1.0-canary.ef756ee

package/src/component/_generated/server.ts

@@ -0,0 +1,156 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  ActionBuilder,
+  HttpActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+} from "convex/server";
+import {
+  actionGeneric,
+  httpActionGeneric,
+  queryGeneric,
+  mutationGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+} from "convex/server";
+import type { DataModel } from "./dataModel.js";
+
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const query: QueryBuilder<DataModel, "public"> = queryGeneric;
+
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const internalQuery: QueryBuilder<DataModel, "internal"> =
+  internalQueryGeneric;
+
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const mutation: MutationBuilder<DataModel, "public"> = mutationGeneric;
+
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const internalMutation: MutationBuilder<DataModel, "internal"> =
+  internalMutationGeneric;
+
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export const action: ActionBuilder<DataModel, "public"> = actionGeneric;
+
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export const internalAction: ActionBuilder<DataModel, "internal"> =
+  internalActionGeneric;
+
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export const httpAction: HttpActionBuilder = httpActionGeneric;
+
+/**
+ * A set of services for use within Convex query functions.
+ *
+ * The query context is passed as the first argument to any Convex query
+ * function run on the server.
+ *
+ * If you're using code generation, use the `QueryCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type QueryCtx = GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex mutation functions.
+ *
+ * The mutation context is passed as the first argument to any Convex mutation
+ * function run on the server.
+ *
+ * If you're using code generation, use the `MutationCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type MutationCtx = GenericMutationCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex action functions.
+ *
+ * The action context is passed as the first argument to any Convex action
+ * function run on the server.
+ */
+export type ActionCtx = GenericActionCtx<DataModel>;
+
+/**
+ * An interface to read from the database within Convex query functions.
+ *
+ * The two entry points are {@link DatabaseReader.get}, which fetches a single
+ * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
+ * building a query.
+ */
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+
+/**
+ * An interface to read from and write to the database within Convex mutation
+ * functions.
+ *
+ * Convex guarantees that all writes within a single mutation are
+ * executed atomically, so you never have to worry about partial writes leaving
+ * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
+ * for the guarantees Convex provides your functions.
+ */
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;

package/src/component/convex.config.ts

@@ -0,0 +1,9 @@
+import { defineComponent } from "convex/server";
+
+const component = defineComponent("reactions");
+
+// Nest official child components here, e.g.:
+// import aggregate from "@convex-dev/aggregate/convex.config";
+// component.use(aggregate);
+
+export default component;

package/src/component/mutations.ts

@@ -0,0 +1,79 @@
+import { v } from "convex/values";
+import { mutation } from "./_generated/server";
+import { reactResult } from "./validators";
+
+/**
+ * Toggle a reaction edge in one transaction. If the subject has no
+ * `(authorRef, resourceRef, kind)` edge it is inserted (`action: "added"`,
+ * `reacted: true`); if it already exists the existing edge is deleted
+ * (`action: "removed"`, `reacted: false`). The read and the write share the
+ * mutation transaction, so two concurrent toggles cannot both insert — the
+ * uniqueness invariant (≤1 edge per subject per kind per resource) holds.
+ *
+ * `createdAt` is stamped from the server clock (`Date.now()` inside the handler
+ * — never caller-supplied). `kind` vocabulary and any allowlist are the host's
+ * concern, enforced at the client boundary before this call.
+ */
+export const react = mutation({
+  args: {
+    authorRef: v.string(),
+    resourceRef: v.string(),
+    kind: v.string(),
+  },
+  returns: reactResult,
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("reactions")
+      .withIndex("by_author_resource_kind", (q) =>
+        q
+          .eq("authorRef", args.authorRef)
+          .eq("resourceRef", args.resourceRef)
+          .eq("kind", args.kind),
+      )
+      .unique();
+
+    if (existing !== null) {
+      await ctx.db.delete(existing._id);
+      return { reacted: false, action: "removed" as const };
+    }
+
+    await ctx.db.insert("reactions", {
+      authorRef: args.authorRef,
+      resourceRef: args.resourceRef,
+      kind: args.kind,
+      createdAt: Date.now(),
+    });
+    return { reacted: true, action: "added" as const };
+  },
+});
+
+/**
+ * Remove a subject's `(authorRef, resourceRef, kind)` reaction edge. Idempotent:
+ * removing an edge that does not exist is a no-op that returns `false`, so a
+ * duplicate or replayed `unreact` is safe. Returns `true` only when an edge was
+ * actually deleted.
+ */
+export const unreact = mutation({
+  args: {
+    authorRef: v.string(),
+    resourceRef: v.string(),
+    kind: v.string(),
+  },
+  returns: v.boolean(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("reactions")
+      .withIndex("by_author_resource_kind", (q) =>
+        q
+          .eq("authorRef", args.authorRef)
+          .eq("resourceRef", args.resourceRef)
+          .eq("kind", args.kind),
+      )
+      .unique();
+    if (existing === null) {
+      return false;
+    }
+    await ctx.db.delete(existing._id);
+    return true;
+  },
+});

package/src/component/queries.ts

@@ -0,0 +1,124 @@
+import { v } from "convex/values";
+import { paginationOptsValidator } from "convex/server";
+import { query } from "./_generated/server";
+import { kindCount, reactionView } from "./validators";
+import type { Doc } from "./_generated/dataModel";
+
+/** Project a stored reaction row to its public view (drops internal fields). */
+function view(row: Doc<"reactions">) {
+  return {
+    authorRef: row.authorRef,
+    resourceRef: row.resourceRef,
+    kind: row.kind,
+    createdAt: row.createdAt,
+  };
+}
+
+/**
+ * Tally reaction edges per `kind` on one resource. Reads every edge for
+ * `resourceRef` via the `by_resource_kind` index (which is prefixed by
+ * `resourceRef`, so a `resourceRef`-only range spans all kinds) and groups them
+ * into `{ kind, count }` rows, sorted by `kind` for a stable order. A resource
+ * with no reactions returns an empty array.
+ */
+export const counts = query({
+  args: { resourceRef: v.string() },
+  returns: v.array(kindCount),
+  handler: async (ctx, args) => {
+    const rows = await ctx.db
+      .query("reactions")
+      .withIndex("by_resource_kind", (q) => q.eq("resourceRef", args.resourceRef))
+      .collect();
+    const tally = new Map<string, number>();
+    for (const row of rows) {
+      tally.set(row.kind, (tally.get(row.kind) ?? 0) + 1);
+    }
+    // Sort by kind for a stable, deterministic order. `localeCompare` is a
+    // single expression (no comparator branch), so coverage stays exact.
+    return [...tally.entries()]
+      .map(([kind, count]) => ({ kind, count }))
+      .sort((a, b) => a.kind.localeCompare(b.kind));
+  },
+});
+
+/**
+ * Whether a subject holds a `(authorRef, resourceRef, kind)` reaction edge. A
+ * unique point read over `by_author_resource_kind` — the per-subject toggle
+ * state the host renders next to a reaction control.
+ */
+export const hasReacted = query({
+  args: {
+    authorRef: v.string(),
+    resourceRef: v.string(),
+    kind: v.string(),
+  },
+  returns: v.boolean(),
+  handler: async (ctx, args) => {
+    const edge = await ctx.db
+      .query("reactions")
+      .withIndex("by_author_resource_kind", (q) =>
+        q
+          .eq("authorRef", args.authorRef)
+          .eq("resourceRef", args.resourceRef)
+          .eq("kind", args.kind),
+      )
+      .unique();
+    return edge !== null;
+  },
+});
+
+/**
+ * Every reaction kind a subject placed on one resource (their own reaction
+ * state across kinds), via the `by_author_resource` index. Returns the list of
+ * `kind` strings; empty when the subject has not reacted to the resource.
+ */
+export const myReactions = query({
+  args: { authorRef: v.string(), resourceRef: v.string() },
+  returns: v.array(v.string()),
+  handler: async (ctx, args) => {
+    const rows = await ctx.db
+      .query("reactions")
+      .withIndex("by_author_resource", (q) =>
+        q.eq("authorRef", args.authorRef).eq("resourceRef", args.resourceRef),
+      )
+      .collect();
+    return rows.map((row) => row.kind);
+  },
+});
+
+/**
+ * Page the subjects who reacted to `resourceRef` with one `kind`, oldest first
+ * via the `by_resource_kind` index. Takes the standard Convex `paginationOpts`
+ * and returns the standard paginated envelope (`page`, `isDone`,
+ * `continueCursor`) so the host can list reactors reactively.
+ */
+export const reactors = query({
+  args: {
+    resourceRef: v.string(),
+    kind: v.string(),
+    paginationOpts: paginationOptsValidator,
+  },
+  returns: v.object({
+    page: v.array(reactionView),
+    isDone: v.boolean(),
+    continueCursor: v.string(),
+    splitCursor: v.optional(v.union(v.string(), v.null())),
+    pageStatus: v.optional(
+      v.union(
+        v.literal("SplitRecommended"),
+        v.literal("SplitRequired"),
+        v.null(),
+      ),
+    ),
+  }),
+  handler: async (ctx, args) => {
+    const result = await ctx.db
+      .query("reactions")
+      .withIndex("by_resource_kind", (q) =>
+        q.eq("resourceRef", args.resourceRef).eq("kind", args.kind),
+      )
+      .order("asc")
+      .paginate(args.paginationOpts);
+    return { ...result, page: result.page.map(view) };
+  },
+});

package/src/component/schema.ts

@@ -0,0 +1,30 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+/**
+ * Sandboxed table — one reaction edge per row. An edge is the opaque triple
+ * `(authorRef, resourceRef, kind)`: a host subject reacted to a host resource
+ * with one reaction kind. `createdAt` is stamped from the server clock. The
+ * component never de-references the opaque refs and never reads host tables.
+ *
+ * Indexes:
+ * - `by_author_resource_kind` — the uniqueness / toggle / dedup key. A
+ *   `(authorRef, resourceRef, kind)` lookup is `.unique()`, so one subject can
+ *   hold at most one edge per kind on a resource (enforced in the mutation
+ *   transaction).
+ * - `by_resource_kind` — count edges of one kind on a resource and page its
+ *   reactors oldest-first.
+ * - `by_author_resource` — list every kind a subject placed on a resource
+ *   (`myReactions`).
+ */
+export default defineSchema({
+  reactions: defineTable({
+    authorRef: v.string(),
+    resourceRef: v.string(),
+    kind: v.string(),
+    createdAt: v.number(),
+  })
+    .index("by_author_resource_kind", ["authorRef", "resourceRef", "kind"])
+    .index("by_resource_kind", ["resourceRef", "kind", "createdAt"])
+    .index("by_author_resource", ["authorRef", "resourceRef"]),
+});

package/src/component/validators.ts

@@ -0,0 +1,33 @@
+import { v } from "convex/values";
+
+/**
+ * Public projection of a stored reaction edge returned by {@link reactors}.
+ * `authorRef` and `resourceRef` are opaque host references the component never
+ * de-references; `kind` is the reaction tag (an emoji, `"up"`/`"down"`, `"like"`
+ * — the host decides the vocabulary and may constrain it with an allowlist).
+ */
+export const reactionView = v.object({
+  authorRef: v.string(),
+  resourceRef: v.string(),
+  kind: v.string(),
+  createdAt: v.number(),
+});
+
+/**
+ * A single `{ kind, count }` tally returned by {@link counts}. The component
+ * counts reaction edges per `kind` on a resource; `kind` is host-defined and
+ * opaque.
+ */
+export const kindCount = v.object({
+  kind: v.string(),
+  count: v.number(),
+});
+
+/**
+ * The result of a toggle {@link react} call: whether the edge now exists
+ * (`reacted`) after the toggle, and the action that produced that state.
+ */
+export const reactResult = v.object({
+  reacted: v.boolean(),
+  action: v.union(v.literal("added"), v.literal("removed")),
+});

package/src/shared.ts

@@ -0,0 +1,8 @@
+/** Shared constants used by both `client/` and `component/`. */
+
+/**
+ * The component id (`defineComponent("reactions")`) and the default mount name a
+ * host gets from `app.use(component)`. Used as the default `register()` mount in
+ * tests so the name is declared in exactly one place.
+ */
+export const COMPONENT_NAME = "reactions";

package/src/test.ts

@@ -0,0 +1,16 @@
+import type { TestConvex } from "convex-test";
+import schema from "./component/schema";
+import { COMPONENT_NAME } from "./shared";
+
+const modules = import.meta.glob("./component/**/*.ts");
+
+/**
+ * Register this component with a `convex-test` instance so consuming apps can
+ * test integration: `import { register } from "@vllnt/convex-reactions/test"`.
+ */
+export function register(
+  t: TestConvex<typeof schema>,
+  name: string = COMPONENT_NAME,
+): void {
+  t.registerComponent(name, schema, modules);
+}