@vllnt/convex-reactions 0.1.0-canary.ef756ee

package/dist/component/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/component/validators.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;kEAKvB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,SAAS;;;;;;gCAGpB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;;oCAGtB,CAAC"}

package/dist/component/validators.js

@@ -0,0 +1,31 @@
+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")),
+});
+//# sourceMappingURL=validators.js.map

package/dist/component/validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.js","sourceRoot":"","sources":["../../src/component/validators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAElC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;CAClB,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACpB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;CAC1D,CAAC,CAAC"}

package/dist/shared.d.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 declare const COMPONENT_NAME = "reactions";
+//# sourceMappingURL=shared.d.ts.map

package/dist/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAEhE;;;;GAIG;AACH,eAAO,MAAM,cAAc,cAAc,CAAC"}

package/dist/shared.js

@@ -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";
+//# sourceMappingURL=shared.js.map

package/dist/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAEhE;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAC"}

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@vllnt/convex-reactions",
+  "version": "0.1.0-canary.ef756ee",
+  "description": "Reactions, votes, and likes on any resource — toggle, count by kind, and list reactors as a Convex component",
+  "license": "MIT",
+  "type": "module",
+  "packageManager": "pnpm@9.15.4",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./test": "./src/test.ts",
+    "./_generated/component.js": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./_generated/component": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./convex.config": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    },
+    "./convex.config.js": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    }
+  },
+  "types": "./dist/client/index.d.ts",
+  "module": "./dist/client/index.js",
+  "scripts": {
+    "build": "tsc --project ./tsconfig.build.json",
+    "build:codegen": "pnpm convex codegen --component-dir ./src/component && pnpm build",
+    "build:clean": "rm -rf dist *.tsbuildinfo && pnpm build:codegen",
+    "typecheck": "tsc --noEmit",
+    "typecheck:ci": "tsc --noEmit --project tsconfig.ci.json",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest --typecheck --clearScreen false",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text",
+    "generate:llms": "node scripts/generate-llms.mjs",
+    "preversion": "pnpm install --frozen-lockfile && pnpm build && pnpm test:coverage && pnpm typecheck && pnpm generate:llms",
+    "prepublishOnly": "npm whoami || npm login",
+    "alpha": "npm version prerelease --preid alpha && npm publish --tag alpha && git push --follow-tags",
+    "release": "npm version patch && npm publish && git push --follow-tags"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "convex": "^1.41.0"
+  },
+  "devDependencies": {
+    "@edge-runtime/vm": "^5.0.0",
+    "@vitest/coverage-v8": "^4.1.8",
+    "@vllnt/eslint-config": "^1.0.0",
+    "@vllnt/typescript": "^1.0.0",
+    "convex": "^1.41.0",
+    "convex-test": "^0.0.53",
+    "eslint": "^9.0.0",
+    "prettier": "^3.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.8"
+  },
+  "homepage": "https://github.com/vllnt/convex-reactions#readme",
+  "bugs": {
+    "url": "https://github.com/vllnt/convex-reactions/issues"
+  },
+  "author": {
+    "name": "bntvllnt",
+    "url": "https://bntvllnt.com"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/bntvllnt"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vllnt/convex-reactions"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "convex",
+    "convex-component",
+    "reactions",
+    "votes",
+    "likes"
+  ]
+}

package/src/client/index.ts

@@ -0,0 +1,213 @@
+import type {
+  FunctionArgs,
+  FunctionReference,
+  FunctionReturnType,
+  PaginationOptions,
+  PaginationResult,
+} from "convex/server";
+import type {
+  KindCount,
+  ReactResult,
+  ReactionView,
+  ReactionsOptions,
+} from "./types.js";
+
+/**
+ * The reactions component's function references, as exposed on the host via
+ * `components.reactions`. The opaque host refs (`authorRef`/`resourceRef`) and
+ * the `kind` are plain strings here; the host owns their meaning.
+ */
+export interface ReactionsComponent {
+  mutations: {
+    react: FunctionReference<
+      "mutation",
+      "internal",
+      { authorRef: string; resourceRef: string; kind: string },
+      ReactResult
+    >;
+    unreact: FunctionReference<
+      "mutation",
+      "internal",
+      { authorRef: string; resourceRef: string; kind: string },
+      boolean
+    >;
+  };
+  queries: {
+    counts: FunctionReference<
+      "query",
+      "internal",
+      { resourceRef: string },
+      KindCount[]
+    >;
+    hasReacted: FunctionReference<
+      "query",
+      "internal",
+      { authorRef: string; resourceRef: string; kind: string },
+      boolean
+    >;
+    myReactions: FunctionReference<
+      "query",
+      "internal",
+      { authorRef: string; resourceRef: string },
+      string[]
+    >;
+    reactors: FunctionReference<
+      "query",
+      "internal",
+      { resourceRef: string; kind: string; paginationOpts: PaginationOptions },
+      PaginationResult<ReactionView>
+    >;
+  };
+}
+
+interface RunQueryCtx {
+  runQuery<Q extends FunctionReference<"query", "internal">>(
+    reference: Q,
+    args: FunctionArgs<Q>,
+  ): Promise<FunctionReturnType<Q>>;
+}
+
+interface RunMutationCtx {
+  runMutation<M extends FunctionReference<"mutation", "internal">>(
+    reference: M,
+    args: FunctionArgs<M>,
+  ): Promise<FunctionReturnType<M>>;
+}
+
+/**
+ * Consumer-facing client for reactions / votes / likes on any resource. A
+ * reaction is the opaque edge `(authorRef, resourceRef, kind)`: a host subject
+ * reacted to a host resource with one reaction kind. One edge per subject per
+ * kind per resource is enforced inside the mutation transaction, so `react`
+ * toggles (add if absent, remove if present) and counts stay correct under
+ * concurrent toggles.
+ *
+ * The host owns meaning and auth — it resolves identity, decides who may react,
+ * and passes opaque `authorRef` / `resourceRef` strings and a `kind`. Pin the
+ * reaction vocabulary with `allowedKinds` to reject unknown kinds at the
+ * boundary; omit it to accept freeform kinds.
+ *
+ * @example
+ * ```ts
+ * const reactions = new Reactions(components.reactions, {
+ *   allowedKinds: ["up", "down"],
+ * });
+ * await reactions.react(ctx, userId, postId, "up");      // toggle a vote
+ * const tally = await reactions.counts(ctx, postId);     // [{ kind: "up", count: 1 }]
+ * const mine = await reactions.myReactions(ctx, userId, postId); // ["up"]
+ * ```
+ */
+export class Reactions {
+  private readonly allowedKinds: ReadonlySet<string> | undefined;
+
+  constructor(
+    private readonly component: ReactionsComponent,
+    options: ReactionsOptions = {},
+  ) {
+    this.allowedKinds =
+      options.allowedKinds === undefined
+        ? undefined
+        : new Set(options.allowedKinds);
+  }
+
+  /** Reject a `kind` outside the configured allowlist (no-op when unset). */
+  private assertKind(kind: string): void {
+    if (this.allowedKinds !== undefined && !this.allowedKinds.has(kind)) {
+      throw new Error(
+        `invalid reaction kind "${kind}": not in the configured allowlist`,
+      );
+    }
+  }
+
+  /**
+   * Toggle a subject's reaction on a resource. Adds the
+   * `(authorRef, resourceRef, kind)` edge if absent, removes it if present, in
+   * one transaction. Returns whether the edge now exists and which side ran.
+   * Throws if `kind` is outside the configured allowlist.
+   */
+  react(
+    ctx: RunMutationCtx,
+    authorRef: string,
+    resourceRef: string,
+    kind: string,
+  ): Promise<ReactResult> {
+    this.assertKind(kind);
+    return ctx.runMutation(this.component.mutations.react, {
+      authorRef,
+      resourceRef,
+      kind,
+    });
+  }
+
+  /**
+   * Remove a subject's reaction edge. Idempotent — removing an edge that does
+   * not exist returns `false`; a real removal returns `true`. Throws if `kind`
+   * is outside the configured allowlist.
+   */
+  unreact(
+    ctx: RunMutationCtx,
+    authorRef: string,
+    resourceRef: string,
+    kind: string,
+  ): Promise<boolean> {
+    this.assertKind(kind);
+    return ctx.runMutation(this.component.mutations.unreact, {
+      authorRef,
+      resourceRef,
+      kind,
+    });
+  }
+
+  /**
+   * Tally reactions per `kind` on a resource — `[{ kind, count }, ...]` sorted
+   * by `kind`. Empty when the resource has no reactions.
+   */
+  counts(ctx: RunQueryCtx, resourceRef: string): Promise<KindCount[]> {
+    return ctx.runQuery(this.component.queries.counts, { resourceRef });
+  }
+
+  /** Whether a subject holds a `(authorRef, resourceRef, kind)` reaction edge. */
+  hasReacted(
+    ctx: RunQueryCtx,
+    authorRef: string,
+    resourceRef: string,
+    kind: string,
+  ): Promise<boolean> {
+    return ctx.runQuery(this.component.queries.hasReacted, {
+      authorRef,
+      resourceRef,
+      kind,
+    });
+  }
+
+  /** Every reaction `kind` a subject placed on one resource (their own state). */
+  myReactions(
+    ctx: RunQueryCtx,
+    authorRef: string,
+    resourceRef: string,
+  ): Promise<string[]> {
+    return ctx.runQuery(this.component.queries.myReactions, {
+      authorRef,
+      resourceRef,
+    });
+  }
+
+  /**
+   * Page the subjects who reacted to a resource with one `kind`, oldest first.
+   * Returns the standard Convex pagination envelope.
+   */
+  reactors(
+    ctx: RunQueryCtx,
+    resourceRef: string,
+    kind: string,
+    paginationOpts: PaginationOptions,
+  ): Promise<PaginationResult<ReactionView>> {
+    return ctx.runQuery(this.component.queries.reactors, {
+      resourceRef,
+      kind,
+      paginationOpts,
+    });
+  }
+}
+
+export type { KindCount, ReactResult, ReactionView, ReactionsOptions };

package/src/client/types.ts

@@ -0,0 +1,40 @@
+/** Public TypeScript surface for the reactions client. */
+
+/** A single reaction edge as returned by {@link Reactions.reactors}. */
+export interface ReactionView {
+  /** The opaque host subject reference that placed the reaction. */
+  authorRef: string;
+  /** The opaque host resource reference the reaction is on. */
+  resourceRef: string;
+  /** The reaction kind (host-defined: an emoji, `"up"`/`"down"`, `"like"`). */
+  kind: string;
+  /** Absolute ms timestamp the edge was created (server clock). */
+  createdAt: number;
+}
+
+/** A per-kind tally returned by {@link Reactions.counts}. */
+export interface KindCount {
+  /** The reaction kind. */
+  kind: string;
+  /** The number of distinct subjects that reacted with this kind. */
+  count: number;
+}
+
+/** The outcome of a toggle {@link Reactions.react} call. */
+export interface ReactResult {
+  /** Whether the subject now holds the edge (true after add, false after remove). */
+  reacted: boolean;
+  /** Which side of the toggle ran. */
+  action: "added" | "removed";
+}
+
+/** Construction options for the {@link Reactions} client. */
+export interface ReactionsOptions {
+  /**
+   * Optional allowlist of permitted reaction `kind` values. When set, `react`
+   * and `unreact` throw before calling the component if `kind` is not in the
+   * list — the host pins its reaction vocabulary (e.g. `["up", "down"]` or a
+   * fixed emoji set). Omit to accept any freeform `kind`.
+   */
+  allowedKinds?: readonly string[];
+}

package/src/component/_generated/api.ts

@@ -0,0 +1,54 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as mutations from "../mutations.js";
+import type * as queries from "../queries.js";
+import type * as validators from "../validators.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+import { anyApi, componentsGeneric } from "convex/server";
+
+const fullApi: ApiFromModules<{
+  mutations: typeof mutations;
+  queries: typeof queries;
+  validators: typeof validators;
+}> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+> = anyApi as any;
+
+export const components = componentsGeneric() as unknown as {};

package/src/component/_generated/component.ts

@@ -0,0 +1,94 @@
+/* eslint-disable */
+/**
+ * Generated `ComponentApi` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type { FunctionReference } from "convex/server";
+
+/**
+ * A utility for referencing a Convex component's exposed API.
+ *
+ * Useful when expecting a parameter like `components.myComponent`.
+ * Usage:
+ * ```ts
+ * async function myFunction(ctx: QueryCtx, component: ComponentApi) {
+ *   return ctx.runQuery(component.someFile.someQuery, { ...args });
+ * }
+ * ```
+ */
+export type ComponentApi<Name extends string | undefined = string | undefined> =
+  {
+    mutations: {
+      react: FunctionReference<
+        "mutation",
+        "internal",
+        { authorRef: string; kind: string; resourceRef: string },
+        { action: "added" | "removed"; reacted: boolean },
+        Name
+      >;
+      unreact: FunctionReference<
+        "mutation",
+        "internal",
+        { authorRef: string; kind: string; resourceRef: string },
+        boolean,
+        Name
+      >;
+    };
+    queries: {
+      counts: FunctionReference<
+        "query",
+        "internal",
+        { resourceRef: string },
+        Array<{ count: number; kind: string }>,
+        Name
+      >;
+      hasReacted: FunctionReference<
+        "query",
+        "internal",
+        { authorRef: string; kind: string; resourceRef: string },
+        boolean,
+        Name
+      >;
+      myReactions: FunctionReference<
+        "query",
+        "internal",
+        { authorRef: string; resourceRef: string },
+        Array<string>,
+        Name
+      >;
+      reactors: FunctionReference<
+        "query",
+        "internal",
+        {
+          kind: string;
+          paginationOpts: {
+            cursor: string | null;
+            endCursor?: string | null;
+            id?: number;
+            maximumBytesRead?: number;
+            maximumRowsRead?: number;
+            numItems: number;
+          };
+          resourceRef: string;
+        },
+        {
+          continueCursor: string;
+          isDone: boolean;
+          page: Array<{
+            authorRef: string;
+            createdAt: number;
+            kind: string;
+            resourceRef: string;
+          }>;
+          pageStatus?: "SplitRecommended" | "SplitRequired" | null;
+          splitCursor?: string | null;
+        },
+        Name
+      >;
+    };
+  };

package/src/component/_generated/dataModel.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;