@convex-dev/sharded-counter 0.1.1

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@convex-dev/sharded-counter",
+  "description": "A sharded counter component for Convex.",
+  "repository": "github:get-convex/sharded-counter",
+  "homepage": "https://github.com/get-convex/sharded-counter#readme",
+  "bugs": {
+    "email": "support@convex.dev",
+    "url": "https://github.com/get-convex/sharded-counter/issues"
+  },
+  "version": "0.1.1",
+  "license": "Apache-2.0",
+  "keywords": [
+    "convex",
+    "count",
+    "component"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs",
+    "build:esm": "tsc --project ./esm.json && echo '{\\n  \"type\": \"module\"\\n}' > dist/esm/package.json",
+    "build:cjs": "tsc --project ./commonjs.json && echo '{\\n  \"type\": \"commonjs\"\\n}' > dist/commonjs/package.json",
+    "dev": "cd example; npm run dev",
+    "typecheck": "tsc --noEmit",
+    "prepare": "npm run build",
+    "prepack": "node node10stubs.mjs",
+    "postpack": "node node10stubs.mjs --cleanup",
+    "test": "vitest run",
+    "test:debug": "vitest --inspect-brk --no-file-parallelism",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text"
+  },
+  "files": [
+    "dist",
+    "src",
+    "react"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "@convex-dev/component-source": "./src/client/index.ts",
+        "types": "./dist/esm/client/index.d.ts",
+        "default": "./dist/esm/client/index.js"
+      },
+      "require": {
+        "@convex-dev/component-source": "./src/client/index.ts",
+        "types": "./dist/commonjs/client/index.d.ts",
+        "default": "./dist/commonjs/client/index.js"
+      }
+    },
+    "./convex.config": {
+      "import": {
+        "@convex-dev/component-source": "./src/component/convex.config.ts",
+        "types": "./dist/esm/component/convex.config.d.ts",
+        "default": "./dist/esm/component/convex.config.js"
+      }
+    }
+  },
+  "peerDependencies": {
+    "convex": "^1.16.4"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.9.1",
+    "@types/node": "^18.17.0",
+    "eslint": "^9.9.1",
+    "convex-test": "^0.0.31",
+    "@fast-check/vitest": "^0.1.3",
+    "globals": "^15.9.0",
+    "vitest": "^2.1.1",
+    "prettier": "3.2.5",
+    "typescript": "~5.0.3",
+    "typescript-eslint": "^8.4.0"
+  },
+  "main": "./dist/commonjs/client/index.js",
+  "types": "./dist/commonjs/client/index.d.ts",
+  "module": "./dist/esm/client/index.js"
+}

package/src/client/index.ts

@@ -0,0 +1,82 @@
+import {
+  Expand,
+  FunctionReference,
+  GenericDataModel,
+  GenericMutationCtx,
+  GenericQueryCtx,
+} from "convex/server";
+import { GenericId } from "convex/values";
+import { api } from "../component/_generated/api";
+
+export class ShardedCounter<Shards extends Record<string, number>> {
+  constructor(
+    public component: UseApi<typeof api>,
+    public options?: { shards?: Shards; defaultShards?: number }
+  ) {}
+  async add<Name extends string = keyof Shards & string>(
+    ctx: RunMutationCtx,
+    name: Name,
+    count: number = 1
+  ) {
+    const shards = this.options?.shards?.[name] ?? this.options?.defaultShards;
+    return ctx.runMutation(this.component.public.add, {
+      name,
+      count,
+      shards,
+    });
+  }
+  async count<Name extends string = keyof Shards & string>(
+    ctx: RunQueryCtx,
+    name: Name
+  ) {
+    return ctx.runQuery(this.component.public.count, { name });
+  }
+  // Another way of exporting functionality
+  for<Name extends string = keyof Shards & string>(name: Name) {
+    return {
+      add: async (ctx: RunMutationCtx, count: number = 1) =>
+        this.add(ctx, name, count),
+      subtract: async (ctx: RunMutationCtx, count: number = 1) =>
+        this.add(ctx, name, -count),
+      inc: async (ctx: RunMutationCtx) => this.add(ctx, name, 1),
+      dec: async (ctx: RunMutationCtx) => this.add(ctx, name, -1),
+      count: async (ctx: RunQueryCtx) => this.count(ctx, name),
+    };
+  }
+}
+
+/* Type utils follow */
+
+type RunQueryCtx = {
+  runQuery: GenericQueryCtx<GenericDataModel>["runQuery"];
+};
+type RunMutationCtx = {
+  runMutation: GenericMutationCtx<GenericDataModel>["runMutation"];
+};
+
+export type OpaqueIds<T> =
+  T extends GenericId<infer _T>
+    ? string
+    : T extends (infer U)[]
+      ? OpaqueIds<U>[]
+      : T extends object
+        ? { [K in keyof T]: OpaqueIds<T[K]> }
+        : T;
+
+export type UseApi<API> = Expand<{
+  [mod in keyof API]: API[mod] extends FunctionReference<
+    infer FType,
+    "public",
+    infer FArgs,
+    infer FReturnType,
+    infer FComponentPath
+  >
+    ? FunctionReference<
+        FType,
+        "internal",
+        OpaqueIds<FArgs>,
+        OpaqueIds<FReturnType>,
+        FComponentPath
+      >
+    : UseApi<API[mod]>;
+}>;

package/src/component/_generated/api.d.ts

@@ -0,0 +1,58 @@
+/* prettier-ignore-start */
+
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as public from "../public.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+/**
+ * A utility for referencing Convex functions in your app's API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+declare const fullApi: ApiFromModules<{
+  public: typeof public;
+}>;
+export type Mounts = {
+  public: {
+    add: FunctionReference<
+      "mutation",
+      "public",
+      { count: number; name: string; shards?: number },
+      null
+    >;
+    count: FunctionReference<"query", "public", { name: string }, number>;
+  };
+};
+// For now fullApiWithMounts is only fullApi which provides
+// jump-to-definition in component client code.
+// Use Mounts for the same type without the inference.
+declare const fullApiWithMounts: typeof fullApi;
+
+export declare const api: FilterApi<
+  typeof fullApiWithMounts,
+  FunctionReference<any, "public">
+>;
+export declare const internal: FilterApi<
+  typeof fullApiWithMounts,
+  FunctionReference<any, "internal">
+>;
+
+export declare const components: {};
+
+/* prettier-ignore-end */

package/src/component/_generated/api.js

@@ -0,0 +1,27 @@
+/* prettier-ignore-start */
+
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import { anyApi, componentsGeneric } from "convex/server";
+
+/**
+ * A utility for referencing Convex functions in your app's API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api = anyApi;
+export const internal = anyApi;
+export const components = componentsGeneric();
+
+/* prettier-ignore-end */

package/src/component/_generated/dataModel.d.ts

@@ -0,0 +1,64 @@
+/* prettier-ignore-start */
+
+/* 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(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>;
+
+/* prettier-ignore-end */

package/src/component/_generated/server.d.ts

@@ -0,0 +1,153 @@
+/* prettier-ignore-start */
+
+/* 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 {
+  ActionBuilder,
+  AnyComponents,
+  HttpActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+  FunctionReference,
+} from "convex/server";
+import type { DataModel } from "./dataModel.js";
+
+type GenericCtx =
+  | GenericActionCtx<DataModel>
+  | GenericMutationCtx<DataModel>
+  | GenericQueryCtx<DataModel>;
+
+/**
+ * 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 declare const query: QueryBuilder<DataModel, "public">;
+
+/**
+ * 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 declare const internalQuery: QueryBuilder<DataModel, "internal">;
+
+/**
+ * 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 declare const mutation: MutationBuilder<DataModel, "public">;
+
+/**
+ * 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 declare const internalMutation: MutationBuilder<DataModel, "internal">;
+
+/**
+ * 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 declare const action: ActionBuilder<DataModel, "public">;
+
+/**
+ * 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 declare const internalAction: ActionBuilder<DataModel, "internal">;
+
+/**
+ * Define an HTTP action.
+ *
+ * This 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 action in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export declare const httpAction: HttpActionBuilder;
+
+/**
+ * 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.
+ *
+ * This differs from the {@link MutationCtx} because all of the services are
+ * read-only.
+ */
+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.
+ */
+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>;
+
+/* prettier-ignore-end */

package/src/component/_generated/server.js

@@ -0,0 +1,94 @@
+/* prettier-ignore-start */
+
+/* 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 {
+  actionGeneric,
+  httpActionGeneric,
+  queryGeneric,
+  mutationGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+  componentsGeneric,
+} from "convex/server";
+
+/**
+ * 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 = 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 = 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 = 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 = 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 = 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 = internalActionGeneric;
+
+/**
+ * Define a Convex HTTP action.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument, and a `Request` object
+ * as its second.
+ * @returns The wrapped endpoint function. Route a URL path to this function in `convex/http.js`.
+ */
+export const httpAction = httpActionGeneric;
+
+/* prettier-ignore-end */

package/src/component/convex.config.ts

@@ -0,0 +1,3 @@
+import { defineComponent } from "convex/server";
+
+export default defineComponent("shardedCounter");

package/src/component/counter.test.ts

@@ -0,0 +1,45 @@
+/// <reference types="vite/client" />
+
+import { describe, expect, test } from "vitest";
+import { convexTest } from "convex-test";
+import schema from "./schema.js";
+import { test as fcTest, fc } from "@fast-check/vitest";
+import { api } from "./_generated/api.js";
+
+const modules = import.meta.glob("./**/*.*s");
+
+describe("counter", () => {
+  test("add and subtract", async () => {
+    const t = convexTest(schema, modules);
+    await t.mutation(api.public.add, { name: "beans", count: 10 });
+    await t.mutation(api.public.add, { name: "beans", count: 5 });
+    expect(await t.query(api.public.count, { name: "beans" })).toEqual(15);
+    await t.mutation(api.public.add, { name: "beans", count: -5 });
+    expect(await t.query(api.public.count, { name: "friends" })).toEqual(0);
+    await t.mutation(api.public.add, { name: "friends", count: 6, shards: 1 });
+    await t.mutation(api.public.add, { name: "friends", count: 2, shards: 1 });
+    await t.mutation(api.public.add, { name: "friends", count: 3, shards: 3 });
+    expect(await t.query(api.public.count, { name: "beans" })).toEqual(10);
+    expect(await t.query(api.public.count, { name: "friends" })).toEqual(11);
+  });
+});
+
+fcTest.prop({
+  updates: fc.array(fc.record({
+    v: fc.integer({ min: 0, max: 10000 }).map((i) => i / 100),
+    key: fc.string(),
+    shards: fc.option(fc.integer({ min: 1, max: 100 })),
+  })),
+})(
+  "updates to counter should match in-memory counter which ignores sharding",
+  async ({ updates }) => {
+    const t = convexTest(schema, modules);
+    const counter = new Map<string, number>();
+    for (const { v, key, shards } of updates) {
+      counter.set(key, (counter.get(key) ?? 0) + v);
+      await t.mutation(api.public.add, { name: key, count: v, shards: shards ?? undefined });
+      const count = await t.query(api.public.count, { name: key });
+      expect(count).toBeCloseTo(counter.get(key)!);
+    }
+  },
+);

package/src/component/public.ts

@@ -0,0 +1,43 @@
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server";
+
+export const DEFAULT_SHARD_COUNT = 16;
+
+export const add = mutation({
+  args: {
+    name: v.string(),
+    count: v.number(),
+    shards: v.optional(v.number()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const shard = Math.floor(Math.random() * (args.shards ?? DEFAULT_SHARD_COUNT));
+    const counter = await ctx.db
+      .query("counters")
+      .withIndex("name", (q) => q.eq("name", args.name).eq("shard", shard))
+      .unique();
+    if (counter) {
+      await ctx.db.patch(counter._id, {
+        value: counter.value + args.count,
+      });
+    } else {
+      await ctx.db.insert("counters", {
+        name: args.name,
+        value: args.count,
+        shard,
+      });
+    }
+  },
+});
+
+export const count = query({
+  args: { name: v.string() },
+  returns: v.number(),
+  handler: async (ctx, args) => {
+    const counters = await ctx.db
+      .query("counters")
+      .withIndex("name", (q) => q.eq("name", args.name))
+      .collect();
+    return counters.reduce((sum, counter) => sum + counter.value, 0);
+  },
+});

package/src/component/schema.ts

@@ -0,0 +1,10 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  counters: defineTable({
+    name: v.string(),
+    value: v.number(),
+    shard: v.number(),
+  }).index("name", ["name", "shard"]),
+});