@convex-dev/sharded-counter 0.1.1 → 0.1.2

package/README.md

@@ -2,6 +2,10 @@
 
 [![npm version](https://badge.fury.io/js/@convex-dev%2Fsharded-counter.svg)](https://badge.fury.io/js/@convex-dev%2Fsharded-counter)
 
+**Note: Convex Components are currently in beta.**
+
+<!-- START: Include on https://convex.dev/components -->
+
 This component adds counters to Convex. It acts as a key-value store from
 string to number, with sharding to increase throughput when updating values.
 
@@ -11,7 +15,7 @@ and cached.
 For example, if you want to display
 [one million checkboxes](https://en.wikipedia.org/wiki/One_Million_Checkboxes)
 [on your Convex site](https://www.youtube.com/watch?v=LRUWplYoejQ), you want to
-count the checkboxes in real-time while allowing lots of the boxes to change in
+count the checkboxes in real-time while allowing a lot of the boxes to change in
 parallel.
 
 More generally, whenever you have a counter that is changing frequently, you
@@ -19,10 +23,12 @@ can use this component to keep track of it efficiently.
 
 ```ts
 export const checkBox = mutation({
-  args: {i: v.number()},
+  args: { i: v.number() },
   handler: async (ctx, args) => {
-    const checkbox = await ctx.db.query("checkboxes")
-      .withIndex("i", q=>q.eq("i", args.i)).unique();
+    const checkbox = await ctx.db
+      .query("checkboxes")
+      .withIndex("i", (q) => q.eq("i", args.i))
+      .unique();
     if (!checkbox.isChecked) {
       await ctx.db.patch(checkbox._id, { isChecked: true });
 
@@ -39,6 +45,18 @@ export const getCount = query({
 });
 ```
 
+This relies on the assumption that you need to frequently modify the counter,
+but only need to read its value from a query, or infrequently in a mutation.
+If you read the count every time you modify it, you lose the sharding benefit.
+
+## Pre-requisite: Convex
+
+You'll need an existing Convex project to use the component.
+Convex is a hosted backend platform, including a database, serverless functions,
+and a ton more you can learn about [here](https://docs.convex.dev/get-started).
+
+Run `npm create convex` or follow any of the [quickstarts](https://docs.convex.dev/home) to set one up.
+
 ## Installation
 
 First, install the component package:
@@ -66,11 +84,9 @@ the installed component.
 
 ```ts
 import { components } from "./_generated/api";
-import { ShardedCounter } from "@convex-dev/counter";
+import { ShardedCounter } from "@convex-dev/sharded-counter";
 
-const counter = new ShardedCounter(components.counter, {
-  ...options
-});
+const counter = new ShardedCounter(components.shardedCounter);
 ```
 
 ## Updating and reading counters
@@ -140,6 +156,9 @@ const friendCounts = new ShardedCounter<Record<Id<"users">, number>>(
   components.shardedCounter,
   { defaultShards: 1 },
 );
+
+// Decrement a user's friend count by 1
+await friendsCount.add(ctx, userId, -1);
 ```
 
 ## Backfilling an existing count
@@ -148,8 +167,12 @@ If you want to count items like documents in a table, you may already have
 documents before installing the ShardedCounter component, and these should be
 accounted for.
 
-The tricky part is making sure to merge active updates to counts with old
-values that you want to backfill.
+The easy version of this is to calculate the value once and add that value, if
+there aren't active requests happening. You can also periodically re-calculate
+the value and update the counter, if there aren't in-flight requests.
+
+The tricky part is handling requests while doing the calculation: making sure to
+merge active updates to counts with old values that you want to backfill.
 
 See example code at the bottom of
 [example/convex/example.ts](example/convex/example.ts).
@@ -158,89 +181,16 @@ Walkthrough of steps:
 
 1. Create `backfillCursor` table in schema.ts
 2. Create a new document in this table, with fields
-`{ creationTime: 0, id: "", isDone: false }`
+   `{ creationTime: 0, id: "", isDone: false }`
 3. Wherever you want to update a counter based on a document changing, wrap the
-update in a conditional, so it only gets updated if the backfill has processed
-that document. In the example, you would be changing `insertUserBeforeBackfill`
-to be implemented as `insertUserDuringBackfill`.
+   update in a conditional, so it only gets updated if the backfill has processed
+   that document. In the example, you would be changing `insertUserBeforeBackfill`
+   to be implemented as `insertUserDuringBackfill`.
 4. Define backfill functions similar to `backfillUsers` and `backfillUsersBatch`
 5. Call `backfillUsersBatch` from the dashboard.
 6. Remove the conditional when updating counters. In the example, you would be
-changing `insertUserDuringBackfill` to be implemented as
-`insertUserAfterBackfill`.
+   changing `insertUserDuringBackfill` to be implemented as
+   `insertUserAfterBackfill`.
 7. Delete the `backfillCursor` table.
 
 <!-- END: Include on https://convex.dev/components -->
-
-# 🧑‍🏫 What is Convex?
-
-[Convex](https://convex.dev) is a hosted backend platform with a
-built-in database that lets you write your
-[database schema](https://docs.convex.dev/database/schemas) and
-[server functions](https://docs.convex.dev/functions) in
-[TypeScript](https://docs.convex.dev/typescript). Server-side database
-[queries](https://docs.convex.dev/functions/query-functions) automatically
-[cache](https://docs.convex.dev/functions/query-functions#caching--reactivity) and
-[subscribe](https://docs.convex.dev/client/react#reactivity) to data, powering a
-[realtime `useQuery` hook](https://docs.convex.dev/client/react#fetching-data) in our
-[React client](https://docs.convex.dev/client/react). There are also clients for
-[Python](https://docs.convex.dev/client/python),
-[Rust](https://docs.convex.dev/client/rust),
-[ReactNative](https://docs.convex.dev/client/react-native), and
-[Node](https://docs.convex.dev/client/javascript), as well as a straightforward
-[HTTP API](https://docs.convex.dev/http-api/).
-
-The database supports
-[NoSQL-style documents](https://docs.convex.dev/database/document-storage) with
-[opt-in schema validation](https://docs.convex.dev/database/schemas),
-[relationships](https://docs.convex.dev/database/document-ids) and
-[custom indexes](https://docs.convex.dev/database/indexes/)
-(including on fields in nested objects).
-
-The
-[`query`](https://docs.convex.dev/functions/query-functions) and
-[`mutation`](https://docs.convex.dev/functions/mutation-functions) server functions have transactional,
-low latency access to the database and leverage our
-[`v8` runtime](https://docs.convex.dev/functions/runtimes) with
-[determinism guardrails](https://docs.convex.dev/functions/runtimes#using-randomness-and-time-in-queries-and-mutations)
-to provide the strongest ACID guarantees on the market:
-immediate consistency,
-serializable isolation, and
-automatic conflict resolution via
-[optimistic multi-version concurrency control](https://docs.convex.dev/database/advanced/occ) (OCC / MVCC).
-
-The [`action` server functions](https://docs.convex.dev/functions/actions) have
-access to external APIs and enable other side-effects and non-determinism in
-either our
-[optimized `v8` runtime](https://docs.convex.dev/functions/runtimes) or a more
-[flexible `node` runtime](https://docs.convex.dev/functions/runtimes#nodejs-runtime).
-
-Functions can run in the background via
-[scheduling](https://docs.convex.dev/scheduling/scheduled-functions) and
-[cron jobs](https://docs.convex.dev/scheduling/cron-jobs).
-
-Development is cloud-first, with
-[hot reloads for server function](https://docs.convex.dev/cli#run-the-convex-dev-server) editing via the
-[CLI](https://docs.convex.dev/cli),
-[preview deployments](https://docs.convex.dev/production/hosting/preview-deployments),
-[logging and exception reporting integrations](https://docs.convex.dev/production/integrations/),
-There is a
-[dashboard UI](https://docs.convex.dev/dashboard) to
-[browse and edit data](https://docs.convex.dev/dashboard/deployments/data),
-[edit environment variables](https://docs.convex.dev/production/environment-variables),
-[view logs](https://docs.convex.dev/dashboard/deployments/logs),
-[run server functions](https://docs.convex.dev/dashboard/deployments/functions), and more.
-
-There are built-in features for
-[reactive pagination](https://docs.convex.dev/database/pagination),
-[file storage](https://docs.convex.dev/file-storage),
-[reactive text search](https://docs.convex.dev/text-search),
-[vector search](https://docs.convex.dev/vector-search),
-[https endpoints](https://docs.convex.dev/functions/http-actions) (for webhooks),
-[snapshot import/export](https://docs.convex.dev/database/import-export/),
-[streaming import/export](https://docs.convex.dev/production/integrations/streaming-import-export), and
-[runtime validation](https://docs.convex.dev/database/schemas#validators) for
-[function arguments](https://docs.convex.dev/functions/args-validation) and
-[database data](https://docs.convex.dev/database/schemas#schema-validation).
-
-Everything scales automatically, and it’s [free to start](https://www.convex.dev/plans).

package/dist/commonjs/client/index.d.ts

@@ -7,17 +7,78 @@ export declare class ShardedCounter<Shards extends Record<string, number>> {
         shards?: Shards | undefined;
         defaultShards?: number | undefined;
     } | undefined;
+    /**
+     * A sharded counter is a map from string -> counter, where each counter can
+     * be incremented or decremented.
+     *
+     * The counter is sharded into multiple documents to allow for higher
+     * throughput of updates. The default number of shards is 16.
+     *
+     * - More shards => higher throughput of updates.
+     * - Fewer shards => lower latency when querying the counter.
+     *
+     * @param options.shards The number of shards for each counter, for fixed
+     *   keys.
+     * @param options.defaultShards The number of shards for each counter, for
+     *   keys not in `options.shards`.
+     */
     constructor(component: UseApi<typeof api>, options?: {
         shards?: Shards | undefined;
         defaultShards?: number | undefined;
     } | undefined);
+    /**
+     * Increase the counter for key `name` by `count`.
+     * If `count` is negative, the counter will decrease.
+     *
+     * @param name The key to update the counter for.
+     * @param count The amount to increment the counter by. Defaults to 1.
+     */
     add<Name extends string = keyof Shards & string>(ctx: RunMutationCtx, name: Name, count?: number): Promise<null>;
+    /**
+     * Gets the counter for key `name`.
+     *
+     * NOTE: this reads from all shards. If used in a mutation, it will contend
+     * with all mutations that update the counter for this key.
+     */
     count<Name extends string = keyof Shards & string>(ctx: RunQueryCtx, name: Name): Promise<number>;
+    /**
+     * Returns an object with methods to update and query the counter for key
+     * `name`. For fixed keys, you can call `counter.for("<key>")` to get methods
+     * for updating or querying the counter for that key. Example:
+     *
+     * ```ts
+     * const counter = new ShardedCounter(components.shardedCounter);
+     * const beanCounter = counter.for("beans");
+     * export const pushPapers = mutation({
+     *  handler: async (ctx) => {
+     *   await beanCounter.inc(ctx);
+     *  },
+     * });
+     * ```
+     */
     for<Name extends string = keyof Shards & string>(name: Name): {
+        /**
+         * Add `count` to the counter.
+         */
         add: (ctx: RunMutationCtx, count?: number) => Promise<null>;
+        /**
+         * Subtract `count` from the counter.
+         */
         subtract: (ctx: RunMutationCtx, count?: number) => Promise<null>;
+        /**
+         * Increment the counter by 1.
+         */
         inc: (ctx: RunMutationCtx) => Promise<null>;
+        /**
+         * Decrement the counter by 1.
+         */
         dec: (ctx: RunMutationCtx) => Promise<null>;
+        /**
+         * Get the current value of the counter.
+         *
+         * NOTE: this reads from all shards. If used in a mutation, it will
+         * contend with all mutations that update the counter for this key.
+         */
         count: (ctx: RunQueryCtx) => Promise<number>;
     };
 }

package/dist/commonjs/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,GAAG,EAAE,MAAM,6BAA6B,CAAC;AAElD,qBAAa,cAAc,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAEtD,SAAS,EAAE,MAAM,CAAC,OAAO,GAAG,CAAC;IAC7B,OAAO,CAAC;;;;gBADR,SAAS,EAAE,MAAM,CAAC,OAAO,GAAG,CAAC,EAC7B,OAAO,CAAC;;;iBAA6C;IAExD,GAAG,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,MAAM,GAAG,MAAM,EACnD,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,IAAI,EACV,KAAK,GAAE,MAAU;IASb,KAAK,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,MAAM,GAAG,MAAM,EACrD,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,IAAI;IAKZ,GAAG,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,IAAI;mBAEtC,cAAc,UAAS,MAAM;wBAExB,cAAc,UAAS,MAAM;mBAElC,cAAc;mBACd,cAAc;qBACZ,WAAW;;CAGnC;AAID,KAAK,WAAW,GAAG;IACjB,QAAQ,EAAE,eAAe,CAAC,gBAAgB,CAAC,CAAC,UAAU,CAAC,CAAC;CACzD,CAAC;AACF,KAAK,cAAc,GAAG;IACpB,WAAW,EAAE,kBAAkB,CAAC,gBAAgB,CAAC,CAAC,aAAa,CAAC,CAAC;CAClE,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,IACrB,CAAC,SAAS,SAAS,CAAC,MAAM,EAAE,CAAC,GACzB,MAAM,GACN,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GACnB,SAAS,CAAC,CAAC,CAAC,EAAE,GACd,CAAC,SAAS,MAAM,GACd;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GACnC,CAAC,CAAC;AAEZ,MAAM,MAAM,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC;KAC9B,GAAG,IAAI,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,SAAS,iBAAiB,CACpD,MAAM,KAAK,EACX,QAAQ,EACR,MAAM,KAAK,EACX,MAAM,WAAW,EACjB,MAAM,cAAc,CACrB,GACG,iBAAiB,CACf,KAAK,EACL,UAAU,EACV,SAAS,CAAC,KAAK,CAAC,EAChB,SAAS,CAAC,WAAW,CAAC,EACtB,cAAc,CACf,GACD,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;CACrB,CAAC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,GAAG,EAAE,MAAM,6BAA6B,CAAC;AAElD,qBAAa,cAAc,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAiBtD,SAAS,EAAE,MAAM,CAAC,OAAO,GAAG,CAAC;IAC7B,OAAO,CAAC;;;;IAjBjB;;;;;;;;;;;;;;OAcG;gBAEM,SAAS,EAAE,MAAM,CAAC,OAAO,GAAG,CAAC,EAC7B,OAAO,CAAC;;;iBAA6C;IAE9D;;;;;;OAMG;IACG,GAAG,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,MAAM,GAAG,MAAM,EACnD,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,IAAI,EACV,KAAK,GAAE,MAAU;IASnB;;;;;OAKG;IACG,KAAK,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,MAAM,GAAG,MAAM,EACrD,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,IAAI;IAIZ;;;;;;;;;;;;;;OAcG;IACH,GAAG,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,IAAI;QAEvD;;WAEG;mBACc,cAAc,UAAS,MAAM;QAE9C;;WAEG;wBACmB,cAAc,UAAS,MAAM;QAEnD;;WAEG;mBACc,cAAc;QAC/B;;WAEG;mBACc,cAAc;QAC/B;;;;;WAKG;qBACgB,WAAW;;CAGnC;AAID,KAAK,WAAW,GAAG;IACjB,QAAQ,EAAE,eAAe,CAAC,gBAAgB,CAAC,CAAC,UAAU,CAAC,CAAC;CACzD,CAAC;AACF,KAAK,cAAc,GAAG;IACpB,WAAW,EAAE,kBAAkB,CAAC,gBAAgB,CAAC,CAAC,aAAa,CAAC,CAAC;CAClE,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,IACrB,CAAC,SAAS,SAAS,CAAC,MAAM,EAAE,CAAC,GACzB,MAAM,GACN,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GACnB,SAAS,CAAC,CAAC,CAAC,EAAE,GACd,CAAC,SAAS,MAAM,GACd;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GACnC,CAAC,CAAC;AAEZ,MAAM,MAAM,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC;KAC9B,GAAG,IAAI,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,SAAS,iBAAiB,CACpD,MAAM,KAAK,EACX,QAAQ,EACR,MAAM,KAAK,EACX,MAAM,WAAW,EACjB,MAAM,cAAc,CACrB,GACG,iBAAiB,CACf,KAAK,EACL,UAAU,EACV,SAAS,CAAC,KAAK,CAAC,EAChB,SAAS,CAAC,WAAW,CAAC,EACtB,cAAc,CACf,GACD,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;CACrB,CAAC,CAAC"}

package/dist/commonjs/client/index.js

@@ -1,10 +1,32 @@
 export class ShardedCounter {
     component;
     options;
+    /**
+     * A sharded counter is a map from string -> counter, where each counter can
+     * be incremented or decremented.
+     *
+     * The counter is sharded into multiple documents to allow for higher
+     * throughput of updates. The default number of shards is 16.
+     *
+     * - More shards => higher throughput of updates.
+     * - Fewer shards => lower latency when querying the counter.
+     *
+     * @param options.shards The number of shards for each counter, for fixed
+     *   keys.
+     * @param options.defaultShards The number of shards for each counter, for
+     *   keys not in `options.shards`.
+     */
     constructor(component, options) {
         this.component = component;
         this.options = options;
     }
+    /**
+     * Increase the counter for key `name` by `count`.
+     * If `count` is negative, the counter will decrease.
+     *
+     * @param name The key to update the counter for.
+     * @param count The amount to increment the counter by. Defaults to 1.
+     */
     async add(ctx, name, count = 1) {
         const shards = this.options?.shards?.[name] ?? this.options?.defaultShards;
         return ctx.runMutation(this.component.public.add, {
@@ -13,16 +35,54 @@ export class ShardedCounter {
             shards,
         });
     }
+    /**
+     * Gets the counter for key `name`.
+     *
+     * NOTE: this reads from all shards. If used in a mutation, it will contend
+     * with all mutations that update the counter for this key.
+     */
     async count(ctx, name) {
         return ctx.runQuery(this.component.public.count, { name });
     }
-    // Another way of exporting functionality
+    /**
+     * Returns an object with methods to update and query the counter for key
+     * `name`. For fixed keys, you can call `counter.for("<key>")` to get methods
+     * for updating or querying the counter for that key. Example:
+     *
+     * ```ts
+     * const counter = new ShardedCounter(components.shardedCounter);
+     * const beanCounter = counter.for("beans");
+     * export const pushPapers = mutation({
+     *  handler: async (ctx) => {
+     *   await beanCounter.inc(ctx);
+     *  },
+     * });
+     * ```
+     */
     for(name) {
         return {
+            /**
+             * Add `count` to the counter.
+             */
             add: async (ctx, count = 1) => this.add(ctx, name, count),
+            /**
+             * Subtract `count` from the counter.
+             */
             subtract: async (ctx, count = 1) => this.add(ctx, name, -count),
+            /**
+             * Increment the counter by 1.
+             */
             inc: async (ctx) => this.add(ctx, name, 1),
+            /**
+             * Decrement the counter by 1.
+             */
             dec: async (ctx) => this.add(ctx, name, -1),
+            /**
+             * Get the current value of the counter.
+             *
+             * NOTE: this reads from all shards. If used in a mutation, it will
+             * contend with all mutations that update the counter for this key.
+             */
             count: async (ctx) => this.count(ctx, name),
         };
     }

package/dist/commonjs/client/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAUA,MAAM,OAAO,cAAc;IAEhB;IACA;IAFT,YACS,SAA6B,EAC7B,OAAqD;QADrD,cAAS,GAAT,SAAS,CAAoB;QAC7B,YAAO,GAAP,OAAO,CAA8C;IAC3D,CAAC;IACJ,KAAK,CAAC,GAAG,CACP,GAAmB,EACnB,IAAU,EACV,QAAgB,CAAC;QAEjB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC;QAC3E,OAAO,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE;YAChD,IAAI;YACJ,KAAK;YACL,MAAM;SACP,CAAC,CAAC;IACL,CAAC;IACD,KAAK,CAAC,KAAK,CACT,GAAgB,EAChB,IAAU;QAEV,OAAO,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,yCAAyC;IACzC,GAAG,CAA8C,IAAU;QACzD,OAAO;YACL,GAAG,EAAE,KAAK,EAAE,GAAmB,EAAE,QAAgB,CAAC,EAAE,EAAE,CACpD,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC;YAC5B,QAAQ,EAAE,KAAK,EAAE,GAAmB,EAAE,QAAgB,CAAC,EAAE,EAAE,CACzD,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC;YAC7B,GAAG,EAAE,KAAK,EAAE,GAAmB,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1D,GAAG,EAAE,KAAK,EAAE,GAAmB,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YAC3D,KAAK,EAAE,KAAK,EAAE,GAAgB,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC;SACzD,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAUA,MAAM,OAAO,cAAc;IAiBhB;IACA;IAjBT;;;;;;;;;;;;;;OAcG;IACH,YACS,SAA6B,EAC7B,OAAqD;QADrD,cAAS,GAAT,SAAS,CAAoB;QAC7B,YAAO,GAAP,OAAO,CAA8C;IAC3D,CAAC;IACJ;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,CACP,GAAmB,EACnB,IAAU,EACV,QAAgB,CAAC;QAEjB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC;QAC3E,OAAO,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE;YAChD,IAAI;YACJ,KAAK;YACL,MAAM;SACP,CAAC,CAAC;IACL,CAAC;IACD;;;;;OAKG;IACH,KAAK,CAAC,KAAK,CACT,GAAgB,EAChB,IAAU;QAEV,OAAO,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD;;;;;;;;;;;;;;OAcG;IACH,GAAG,CAA8C,IAAU;QACzD,OAAO;YACL;;eAEG;YACH,GAAG,EAAE,KAAK,EAAE,GAAmB,EAAE,QAAgB,CAAC,EAAE,EAAE,CACpD,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC;YAC5B;;eAEG;YACH,QAAQ,EAAE,KAAK,EAAE,GAAmB,EAAE,QAAgB,CAAC,EAAE,EAAE,CACzD,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC;YAC7B;;eAEG;YACH,GAAG,EAAE,KAAK,EAAE,GAAmB,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1D;;eAEG;YACH,GAAG,EAAE,KAAK,EAAE,GAAmB,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YAC3D;;;;;eAKG;YACH,KAAK,EAAE,KAAK,EAAE,GAAgB,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC;SACzD,CAAC;IACJ,CAAC;CACF"}

package/dist/esm/client/index.d.ts

@@ -7,17 +7,78 @@ export declare class ShardedCounter<Shards extends Record<string, number>> {
         shards?: Shards | undefined;
         defaultShards?: number | undefined;
     } | undefined;
+    /**
+     * A sharded counter is a map from string -> counter, where each counter can
+     * be incremented or decremented.
+     *
+     * The counter is sharded into multiple documents to allow for higher
+     * throughput of updates. The default number of shards is 16.
+     *
+     * - More shards => higher throughput of updates.
+     * - Fewer shards => lower latency when querying the counter.
+     *
+     * @param options.shards The number of shards for each counter, for fixed
+     *   keys.
+     * @param options.defaultShards The number of shards for each counter, for
+     *   keys not in `options.shards`.
+     */
     constructor(component: UseApi<typeof api>, options?: {
         shards?: Shards | undefined;
         defaultShards?: number | undefined;
     } | undefined);
+    /**
+     * Increase the counter for key `name` by `count`.
+     * If `count` is negative, the counter will decrease.
+     *
+     * @param name The key to update the counter for.
+     * @param count The amount to increment the counter by. Defaults to 1.
+     */
     add<Name extends string = keyof Shards & string>(ctx: RunMutationCtx, name: Name, count?: number): Promise<null>;
+    /**
+     * Gets the counter for key `name`.
+     *
+     * NOTE: this reads from all shards. If used in a mutation, it will contend
+     * with all mutations that update the counter for this key.
+     */
     count<Name extends string = keyof Shards & string>(ctx: RunQueryCtx, name: Name): Promise<number>;
+    /**
+     * Returns an object with methods to update and query the counter for key
+     * `name`. For fixed keys, you can call `counter.for("<key>")` to get methods
+     * for updating or querying the counter for that key. Example:
+     *
+     * ```ts
+     * const counter = new ShardedCounter(components.shardedCounter);
+     * const beanCounter = counter.for("beans");
+     * export const pushPapers = mutation({
+     *  handler: async (ctx) => {
+     *   await beanCounter.inc(ctx);
+     *  },
+     * });
+     * ```
+     */
     for<Name extends string = keyof Shards & string>(name: Name): {
+        /**
+         * Add `count` to the counter.
+         */
         add: (ctx: RunMutationCtx, count?: number) => Promise<null>;
+        /**
+         * Subtract `count` from the counter.
+         */
         subtract: (ctx: RunMutationCtx, count?: number) => Promise<null>;
+        /**
+         * Increment the counter by 1.
+         */
         inc: (ctx: RunMutationCtx) => Promise<null>;
+        /**
+         * Decrement the counter by 1.
+         */
         dec: (ctx: RunMutationCtx) => Promise<null>;
+        /**
+         * Get the current value of the counter.
+         *
+         * NOTE: this reads from all shards. If used in a mutation, it will
+         * contend with all mutations that update the counter for this key.
+         */
         count: (ctx: RunQueryCtx) => Promise<number>;
     };
 }

package/dist/esm/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,GAAG,EAAE,MAAM,6BAA6B,CAAC;AAElD,qBAAa,cAAc,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAEtD,SAAS,EAAE,MAAM,CAAC,OAAO,GAAG,CAAC;IAC7B,OAAO,CAAC;;;;gBADR,SAAS,EAAE,MAAM,CAAC,OAAO,GAAG,CAAC,EAC7B,OAAO,CAAC;;;iBAA6C;IAExD,GAAG,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,MAAM,GAAG,MAAM,EACnD,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,IAAI,EACV,KAAK,GAAE,MAAU;IASb,KAAK,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,MAAM,GAAG,MAAM,EACrD,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,IAAI;IAKZ,GAAG,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,IAAI;mBAEtC,cAAc,UAAS,MAAM;wBAExB,cAAc,UAAS,MAAM;mBAElC,cAAc;mBACd,cAAc;qBACZ,WAAW;;CAGnC;AAID,KAAK,WAAW,GAAG;IACjB,QAAQ,EAAE,eAAe,CAAC,gBAAgB,CAAC,CAAC,UAAU,CAAC,CAAC;CACzD,CAAC;AACF,KAAK,cAAc,GAAG;IACpB,WAAW,EAAE,kBAAkB,CAAC,gBAAgB,CAAC,CAAC,aAAa,CAAC,CAAC;CAClE,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,IACrB,CAAC,SAAS,SAAS,CAAC,MAAM,EAAE,CAAC,GACzB,MAAM,GACN,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GACnB,SAAS,CAAC,CAAC,CAAC,EAAE,GACd,CAAC,SAAS,MAAM,GACd;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GACnC,CAAC,CAAC;AAEZ,MAAM,MAAM,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC;KAC9B,GAAG,IAAI,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,SAAS,iBAAiB,CACpD,MAAM,KAAK,EACX,QAAQ,EACR,MAAM,KAAK,EACX,MAAM,WAAW,EACjB,MAAM,cAAc,CACrB,GACG,iBAAiB,CACf,KAAK,EACL,UAAU,EACV,SAAS,CAAC,KAAK,CAAC,EAChB,SAAS,CAAC,WAAW,CAAC,EACtB,cAAc,CACf,GACD,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;CACrB,CAAC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,GAAG,EAAE,MAAM,6BAA6B,CAAC;AAElD,qBAAa,cAAc,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAiBtD,SAAS,EAAE,MAAM,CAAC,OAAO,GAAG,CAAC;IAC7B,OAAO,CAAC;;;;IAjBjB;;;;;;;;;;;;;;OAcG;gBAEM,SAAS,EAAE,MAAM,CAAC,OAAO,GAAG,CAAC,EAC7B,OAAO,CAAC;;;iBAA6C;IAE9D;;;;;;OAMG;IACG,GAAG,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,MAAM,GAAG,MAAM,EACnD,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,IAAI,EACV,KAAK,GAAE,MAAU;IASnB;;;;;OAKG;IACG,KAAK,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,MAAM,GAAG,MAAM,EACrD,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,IAAI;IAIZ;;;;;;;;;;;;;;OAcG;IACH,GAAG,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,IAAI;QAEvD;;WAEG;mBACc,cAAc,UAAS,MAAM;QAE9C;;WAEG;wBACmB,cAAc,UAAS,MAAM;QAEnD;;WAEG;mBACc,cAAc;QAC/B;;WAEG;mBACc,cAAc;QAC/B;;;;;WAKG;qBACgB,WAAW;;CAGnC;AAID,KAAK,WAAW,GAAG;IACjB,QAAQ,EAAE,eAAe,CAAC,gBAAgB,CAAC,CAAC,UAAU,CAAC,CAAC;CACzD,CAAC;AACF,KAAK,cAAc,GAAG;IACpB,WAAW,EAAE,kBAAkB,CAAC,gBAAgB,CAAC,CAAC,aAAa,CAAC,CAAC;CAClE,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,IACrB,CAAC,SAAS,SAAS,CAAC,MAAM,EAAE,CAAC,GACzB,MAAM,GACN,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GACnB,SAAS,CAAC,CAAC,CAAC,EAAE,GACd,CAAC,SAAS,MAAM,GACd;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GACnC,CAAC,CAAC;AAEZ,MAAM,MAAM,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC;KAC9B,GAAG,IAAI,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,SAAS,iBAAiB,CACpD,MAAM,KAAK,EACX,QAAQ,EACR,MAAM,KAAK,EACX,MAAM,WAAW,EACjB,MAAM,cAAc,CACrB,GACG,iBAAiB,CACf,KAAK,EACL,UAAU,EACV,SAAS,CAAC,KAAK,CAAC,EAChB,SAAS,CAAC,WAAW,CAAC,EACtB,cAAc,CACf,GACD,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;CACrB,CAAC,CAAC"}

package/dist/esm/client/index.js

@@ -1,10 +1,32 @@
 export class ShardedCounter {
     component;
     options;
+    /**
+     * A sharded counter is a map from string -> counter, where each counter can
+     * be incremented or decremented.
+     *
+     * The counter is sharded into multiple documents to allow for higher
+     * throughput of updates. The default number of shards is 16.
+     *
+     * - More shards => higher throughput of updates.
+     * - Fewer shards => lower latency when querying the counter.
+     *
+     * @param options.shards The number of shards for each counter, for fixed
+     *   keys.
+     * @param options.defaultShards The number of shards for each counter, for
+     *   keys not in `options.shards`.
+     */
     constructor(component, options) {
         this.component = component;
         this.options = options;
     }
+    /**
+     * Increase the counter for key `name` by `count`.
+     * If `count` is negative, the counter will decrease.
+     *
+     * @param name The key to update the counter for.
+     * @param count The amount to increment the counter by. Defaults to 1.
+     */
     async add(ctx, name, count = 1) {
         const shards = this.options?.shards?.[name] ?? this.options?.defaultShards;
         return ctx.runMutation(this.component.public.add, {
@@ -13,16 +35,54 @@ export class ShardedCounter {
             shards,
         });
     }
+    /**
+     * Gets the counter for key `name`.
+     *
+     * NOTE: this reads from all shards. If used in a mutation, it will contend
+     * with all mutations that update the counter for this key.
+     */
     async count(ctx, name) {
         return ctx.runQuery(this.component.public.count, { name });
     }
-    // Another way of exporting functionality
+    /**
+     * Returns an object with methods to update and query the counter for key
+     * `name`. For fixed keys, you can call `counter.for("<key>")` to get methods
+     * for updating or querying the counter for that key. Example:
+     *
+     * ```ts
+     * const counter = new ShardedCounter(components.shardedCounter);
+     * const beanCounter = counter.for("beans");
+     * export const pushPapers = mutation({
+     *  handler: async (ctx) => {
+     *   await beanCounter.inc(ctx);
+     *  },
+     * });
+     * ```
+     */
     for(name) {
         return {
+            /**
+             * Add `count` to the counter.
+             */
             add: async (ctx, count = 1) => this.add(ctx, name, count),
+            /**
+             * Subtract `count` from the counter.
+             */
             subtract: async (ctx, count = 1) => this.add(ctx, name, -count),
+            /**
+             * Increment the counter by 1.
+             */
             inc: async (ctx) => this.add(ctx, name, 1),
+            /**
+             * Decrement the counter by 1.
+             */
             dec: async (ctx) => this.add(ctx, name, -1),
+            /**
+             * Get the current value of the counter.
+             *
+             * NOTE: this reads from all shards. If used in a mutation, it will
+             * contend with all mutations that update the counter for this key.
+             */
             count: async (ctx) => this.count(ctx, name),
         };
     }

package/dist/esm/client/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAUA,MAAM,OAAO,cAAc;IAEhB;IACA;IAFT,YACS,SAA6B,EAC7B,OAAqD;QADrD,cAAS,GAAT,SAAS,CAAoB;QAC7B,YAAO,GAAP,OAAO,CAA8C;IAC3D,CAAC;IACJ,KAAK,CAAC,GAAG,CACP,GAAmB,EACnB,IAAU,EACV,QAAgB,CAAC;QAEjB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC;QAC3E,OAAO,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE;YAChD,IAAI;YACJ,KAAK;YACL,MAAM;SACP,CAAC,CAAC;IACL,CAAC;IACD,KAAK,CAAC,KAAK,CACT,GAAgB,EAChB,IAAU;QAEV,OAAO,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,yCAAyC;IACzC,GAAG,CAA8C,IAAU;QACzD,OAAO;YACL,GAAG,EAAE,KAAK,EAAE,GAAmB,EAAE,QAAgB,CAAC,EAAE,EAAE,CACpD,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC;YAC5B,QAAQ,EAAE,KAAK,EAAE,GAAmB,EAAE,QAAgB,CAAC,EAAE,EAAE,CACzD,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC;YAC7B,GAAG,EAAE,KAAK,EAAE,GAAmB,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1D,GAAG,EAAE,KAAK,EAAE,GAAmB,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YAC3D,KAAK,EAAE,KAAK,EAAE,GAAgB,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC;SACzD,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAUA,MAAM,OAAO,cAAc;IAiBhB;IACA;IAjBT;;;;;;;;;;;;;;OAcG;IACH,YACS,SAA6B,EAC7B,OAAqD;QADrD,cAAS,GAAT,SAAS,CAAoB;QAC7B,YAAO,GAAP,OAAO,CAA8C;IAC3D,CAAC;IACJ;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,CACP,GAAmB,EACnB,IAAU,EACV,QAAgB,CAAC;QAEjB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC;QAC3E,OAAO,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE;YAChD,IAAI;YACJ,KAAK;YACL,MAAM;SACP,CAAC,CAAC;IACL,CAAC;IACD;;;;;OAKG;IACH,KAAK,CAAC,KAAK,CACT,GAAgB,EAChB,IAAU;QAEV,OAAO,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD;;;;;;;;;;;;;;OAcG;IACH,GAAG,CAA8C,IAAU;QACzD,OAAO;YACL;;eAEG;YACH,GAAG,EAAE,KAAK,EAAE,GAAmB,EAAE,QAAgB,CAAC,EAAE,EAAE,CACpD,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC;YAC5B;;eAEG;YACH,QAAQ,EAAE,KAAK,EAAE,GAAmB,EAAE,QAAgB,CAAC,EAAE,EAAE,CACzD,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC;YAC7B;;eAEG;YACH,GAAG,EAAE,KAAK,EAAE,GAAmB,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1D;;eAEG;YACH,GAAG,EAAE,KAAK,EAAE,GAAmB,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YAC3D;;;;;eAKG;YACH,KAAK,EAAE,KAAK,EAAE,GAAgB,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC;SACzD,CAAC;IACJ,CAAC;CACF"}

package/package.json

@@ -7,7 +7,7 @@
     "email": "support@convex.dev",
     "url": "https://github.com/get-convex/sharded-counter/issues"
   },
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "Apache-2.0",
   "keywords": [
     "convex",
@@ -22,16 +22,13 @@
     "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"
+    "src"
   ],
   "exports": {
     "./package.json": "./package.json",
@@ -56,7 +53,7 @@
     }
   },
   "peerDependencies": {
-    "convex": "^1.16.4"
+    "convex": "~1.16.5 || ~1.17.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.9.1",

package/src/client/index.ts

@@ -9,10 +9,32 @@ import { GenericId } from "convex/values";
 import { api } from "../component/_generated/api";
 
 export class ShardedCounter<Shards extends Record<string, number>> {
+  /**
+   * A sharded counter is a map from string -> counter, where each counter can
+   * be incremented or decremented.
+   * 
+   * The counter is sharded into multiple documents to allow for higher
+   * throughput of updates. The default number of shards is 16.
+   * 
+   * - More shards => higher throughput of updates.
+   * - Fewer shards => lower latency when querying the counter.
+   * 
+   * @param options.shards The number of shards for each counter, for fixed
+   *   keys.
+   * @param options.defaultShards The number of shards for each counter, for
+   *   keys not in `options.shards`.
+   */
   constructor(
     public component: UseApi<typeof api>,
     public options?: { shards?: Shards; defaultShards?: number }
   ) {}
+  /**
+   * Increase the counter for key `name` by `count`.
+   * If `count` is negative, the counter will decrease.
+   * 
+   * @param name The key to update the counter for.
+   * @param count The amount to increment the counter by. Defaults to 1.
+   */
   async add<Name extends string = keyof Shards & string>(
     ctx: RunMutationCtx,
     name: Name,
@@ -25,21 +47,59 @@ export class ShardedCounter<Shards extends Record<string, number>> {
       shards,
     });
   }
+  /**
+   * Gets the counter for key `name`.
+   *
+   * NOTE: this reads from all shards. If used in a mutation, it will contend
+   * with all mutations that update the counter for this key.
+   */
   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
+  /**
+   * Returns an object with methods to update and query the counter for key
+   * `name`. For fixed keys, you can call `counter.for("<key>")` to get methods
+   * for updating or querying the counter for that key. Example:
+   *
+   * ```ts
+   * const counter = new ShardedCounter(components.shardedCounter);
+   * const beanCounter = counter.for("beans");
+   * export const pushPapers = mutation({
+   *  handler: async (ctx) => {
+   *   await beanCounter.inc(ctx);
+   *  },
+   * });
+   * ```
+   */
   for<Name extends string = keyof Shards & string>(name: Name) {
     return {
+      /**
+       * Add `count` to the counter.
+       */
       add: async (ctx: RunMutationCtx, count: number = 1) =>
         this.add(ctx, name, count),
+      /**
+       * Subtract `count` from the counter.
+       */
       subtract: async (ctx: RunMutationCtx, count: number = 1) =>
         this.add(ctx, name, -count),
+      /**
+       * Increment the counter by 1.
+       */
       inc: async (ctx: RunMutationCtx) => this.add(ctx, name, 1),
+      /**
+       * Decrement the counter by 1.
+       */
       dec: async (ctx: RunMutationCtx) => this.add(ctx, name, -1),
+      /**
+       * Get the current value of the counter.
+       * 
+       * NOTE: this reads from all shards. If used in a mutation, it will
+       * contend with all mutations that update the counter for this key.
+       */
       count: async (ctx: RunQueryCtx) => this.count(ctx, name),
     };
   }