@convex-dev/sharded-counter 0.1.3 → 0.1.4

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

@@ -1,7 +1,11 @@
-import { Expand, FunctionReference, GenericDataModel, GenericMutationCtx, GenericQueryCtx } from "convex/server";
+import { DocumentByName, Expand, FunctionReference, GenericDataModel, GenericMutationCtx, GenericQueryCtx, TableNamesInDataModel } from "convex/server";
 import { GenericId } from "convex/values";
 import { api } from "../component/_generated/api";
-export declare class ShardedCounter<Shards extends Record<string, number>> {
+/**
+ * A sharded counter is a map from string -> counter, where each counter can
+ * be incremented or decremented atomically.
+ */
+export declare class ShardedCounter<ShardsKey extends string> {
     private component;
     private options?;
     /**
@@ -20,7 +24,7 @@ export declare class ShardedCounter<Shards extends Record<string, number>> {
      *   keys not in `options.shards`.
      */
     constructor(component: UseApi<typeof api>, options?: {
-        shards?: Shards | undefined;
+        shards?: Record<ShardsKey, number> | undefined;
         defaultShards?: number | undefined;
     } | undefined);
     /**
@@ -30,14 +34,51 @@ export declare class ShardedCounter<Shards extends Record<string, number>> {
      * @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>;
+    add<Name extends string = ShardsKey>(ctx: RunMutationCtx, name: Name, count?: number): Promise<null>;
+    /**
+     * Decrease the counter for key `name` by `count`.
+     */
+    subtract<Name extends string = ShardsKey>(ctx: RunMutationCtx, name: Name, count?: number): Promise<null>;
+    /**
+     * Increment the counter for key `name` by 1.
+     */
+    inc<Name extends string = ShardsKey>(ctx: RunMutationCtx, name: Name): Promise<null>;
+    /**
+     * Decrement the counter for key `name` by 1.
+     */
+    dec<Name extends string = ShardsKey>(ctx: RunMutationCtx, name: Name): 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>;
+    count<Name extends string = ShardsKey>(ctx: RunQueryCtx, name: Name): Promise<number>;
+    /**
+     * Redistribute counts evenly across the counter's shards.
+     *
+     * If there were more shards for this counter at some point, those shards
+     * will be removed.
+     *
+     * If there were fewer shards for this counter, or if the random distribution
+     * of counts is uneven, the counts will be redistributed evenly.
+     *
+     * This operation reads and writes all shards, so it can cause contention if
+     * called too often.
+     */
+    rebalance<Name extends string = ShardsKey>(ctx: RunMutationCtx, name: Name): Promise<void>;
+    /**
+     * Estimate the count of a counter by only reading from a subset of shards,
+     * and extrapolating the total count.
+     *
+     * After a `rebalance`, or if there were a lot of data points to yield a
+     * random distribution across shards, this should be a good approximation of
+     * the total count. If there are few data points, which are not evenly
+     * distributed across shards, this will be a poor approximation.
+     *
+     * Use this to reduce contention when reading the counter.
+     */
+    estimateCount<Name extends string = ShardsKey>(ctx: RunQueryCtx, name: Name, readFromShards?: number): 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
@@ -53,7 +94,7 @@ export declare class ShardedCounter<Shards extends Record<string, number>> {
      * });
      * ```
      */
-    for<Name extends string = keyof Shards & string>(name: Name): {
+    for<Name extends string = ShardsKey>(name: Name): {
         /**
          * Add `count` to the counter.
          */
@@ -77,8 +118,40 @@ export declare class ShardedCounter<Shards extends Record<string, number>> {
          * contend with all mutations that update the counter for this key.
          */
         count: (ctx: RunQueryCtx) => Promise<number>;
+        /**
+         * Redistribute counts evenly across the counter's shards.
+         *
+         * This operation reads and writes all shards, so it can cause contention
+         * if called too often.
+         */
+        rebalance: (ctx: RunMutationCtx) => Promise<void>;
+        /**
+         * Estimate the counter by only reading from a subset of shards,
+         * and extrapolating the total count.
+         *
+         * Use this to reduce contention when reading the counter.
+         */
+        estimateCount: (ctx: RunQueryCtx, readFromShards?: number) => Promise<number>;
     };
+    trigger<Ctx extends RunMutationCtx, Name extends string = ShardsKey>(name: Name): Trigger<Ctx, GenericDataModel, TableNamesInDataModel<GenericDataModel>>;
+    private shardsForKey;
 }
+export type Trigger<Ctx, DataModel extends GenericDataModel, TableName extends TableNamesInDataModel<DataModel>> = (ctx: Ctx, change: Change<DataModel, TableName>) => Promise<void>;
+export type Change<DataModel extends GenericDataModel, TableName extends TableNamesInDataModel<DataModel>> = {
+    id: GenericId<TableName>;
+} & ({
+    operation: "insert";
+    oldDoc: null;
+    newDoc: DocumentByName<DataModel, TableName>;
+} | {
+    operation: "update";
+    oldDoc: DocumentByName<DataModel, TableName>;
+    newDoc: DocumentByName<DataModel, TableName>;
+} | {
+    operation: "delete";
+    oldDoc: DocumentByName<DataModel, TableName>;
+    newDoc: null;
+});
 type RunQueryCtx = {
     runQuery: GenericQueryCtx<GenericDataModel>["runQuery"];
 };

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;IAiB7D,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,OAAO,CAAC;IAjBlB;;;;;;;;;;;;;;OAcG;gBAEO,SAAS,EAAE,MAAM,CAAC,OAAO,GAAG,CAAC,EAC7B,OAAO,CAAC;;;iBAA6C;IAE/D;;;;;;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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/client/index.js

@@ -1,3 +1,7 @@
+/**
+ * A sharded counter is a map from string -> counter, where each counter can
+ * be incremented or decremented atomically.
+ */
 export class ShardedCounter {
     component;
     options;
@@ -28,13 +32,30 @@ export class ShardedCounter {
      * @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, {
             name,
             count,
-            shards,
+            shards: this.shardsForKey(name),
         });
     }
+    /**
+     * Decrease the counter for key `name` by `count`.
+     */
+    async subtract(ctx, name, count = 1) {
+        return this.add(ctx, name, -count);
+    }
+    /**
+     * Increment the counter for key `name` by 1.
+     */
+    async inc(ctx, name) {
+        return this.add(ctx, name, 1);
+    }
+    /**
+     * Decrement the counter for key `name` by 1.
+     */
+    async dec(ctx, name) {
+        return this.add(ctx, name, -1);
+    }
     /**
      * Gets the counter for key `name`.
      *
@@ -44,6 +65,42 @@ export class ShardedCounter {
     async count(ctx, name) {
         return ctx.runQuery(this.component.public.count, { name });
     }
+    /**
+     * Redistribute counts evenly across the counter's shards.
+     *
+     * If there were more shards for this counter at some point, those shards
+     * will be removed.
+     *
+     * If there were fewer shards for this counter, or if the random distribution
+     * of counts is uneven, the counts will be redistributed evenly.
+     *
+     * This operation reads and writes all shards, so it can cause contention if
+     * called too often.
+     */
+    async rebalance(ctx, name) {
+        await ctx.runMutation(this.component.public.rebalance, {
+            name,
+            shards: this.shardsForKey(name),
+        });
+    }
+    /**
+     * Estimate the count of a counter by only reading from a subset of shards,
+     * and extrapolating the total count.
+     *
+     * After a `rebalance`, or if there were a lot of data points to yield a
+     * random distribution across shards, this should be a good approximation of
+     * the total count. If there are few data points, which are not evenly
+     * distributed across shards, this will be a poor approximation.
+     *
+     * Use this to reduce contention when reading the counter.
+     */
+    async estimateCount(ctx, name, readFromShards = 1) {
+        return await ctx.runQuery(this.component.public.estimateCount, {
+            name,
+            shards: this.shardsForKey(name),
+            readFromShards,
+        });
+    }
     /**
      * 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
@@ -84,7 +141,35 @@ export class ShardedCounter {
              * contend with all mutations that update the counter for this key.
              */
             count: async (ctx) => this.count(ctx, name),
+            /**
+             * Redistribute counts evenly across the counter's shards.
+             *
+             * This operation reads and writes all shards, so it can cause contention
+             * if called too often.
+             */
+            rebalance: async (ctx) => this.rebalance(ctx, name),
+            /**
+             * Estimate the counter by only reading from a subset of shards,
+             * and extrapolating the total count.
+             *
+             * Use this to reduce contention when reading the counter.
+             */
+            estimateCount: async (ctx, readFromShards = 1) => this.estimateCount(ctx, name, readFromShards),
+        };
+    }
+    trigger(name) {
+        return async (ctx, change) => {
+            if (change.operation === "insert") {
+                await this.inc(ctx, name);
+            }
+            else if (change.operation === "delete") {
+                await this.dec(ctx, name);
+            }
         };
     }
+    shardsForKey(name) {
+        const explicitShards = this.options?.shards?.[name];
+        return explicitShards ?? this.options?.defaultShards;
+    }
 }
 //# sourceMappingURL=index.js.map

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;IAiBf;IACA;IAjBV;;;;;;;;;;;;;;OAcG;IACH,YACU,SAA6B,EAC7B,OAAqD;QADrD,cAAS,GAAT,SAAS,CAAoB;QAC7B,YAAO,GAAP,OAAO,CAA8C;IAC5D,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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/component/_generated/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../../src/component/_generated/api.js"],"names":[],"mappings":"AAcA;;;;;;;GAOG;AACH,iDAA0B;AAC1B,sDAA+B;AAC/B;;EAA8C"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../../src/component/_generated/api.js"],"names":[],"mappings":"AAYA;;;;;;;GAOG;AACH,iDAA0B;AAC1B,sDAA+B;AAC/B;;EAA8C"}

package/dist/esm/component/_generated/api.js

@@ -1,4 +1,3 @@
-/* prettier-ignore-start */
 /* eslint-disable */
 /**
  * Generated `api` utility.
@@ -20,5 +19,4 @@ import { anyApi, componentsGeneric } from "convex/server";
 export const api = anyApi;
 export const internal = anyApi;
 export const components = componentsGeneric();
-/* prettier-ignore-end */
 //# sourceMappingURL=api.js.map

package/dist/esm/component/_generated/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../../../../src/component/_generated/api.js"],"names":[],"mappings":"AAAA,2BAA2B;AAE3B,oBAAoB;AACpB;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE1D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,MAAM,CAAC;AAC1B,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC;AAC/B,MAAM,CAAC,MAAM,UAAU,GAAG,iBAAiB,EAAE,CAAC;AAE9C,yBAAyB"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../../../src/component/_generated/api.js"],"names":[],"mappings":"AAAA,oBAAoB;AACpB;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE1D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,MAAM,CAAC;AAC1B,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC;AAC/B,MAAM,CAAC,MAAM,UAAU,GAAG,iBAAiB,EAAE,CAAC"}

package/dist/esm/component/_generated/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../../src/component/_generated/server.js"],"names":[],"mappings":"AAuBA;;;;;;;GAOG;AACH,wEAAkC;AAElC;;;;;;;GAOG;AACH,kFAAkD;AAElD;;;;;;;GAOG;AACH,8EAAwC;AAExC;;;;;;;GAOG;AACH,wFAAwD;AAExD;;;;;;;;;;GAUG;AACH,0EAAoC;AAEpC;;;;;GAKG;AACH,oFAAoD;AAEpD;;;;;;GAMG;AACH,8MAA4C"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../../src/component/_generated/server.js"],"names":[],"mappings":"AAqBA;;;;;;;GAOG;AACH,wEAAkC;AAElC;;;;;;;GAOG;AACH,kFAAkD;AAElD;;;;;;;GAOG;AACH,8EAAwC;AAExC;;;;;;;GAOG;AACH,wFAAwD;AAExD;;;;;;;;;;GAUG;AACH,0EAAoC;AAEpC;;;;;GAKG;AACH,oFAAoD;AAEpD;;;;;;GAMG;AACH,8MAA4C"}

package/dist/esm/component/_generated/server.js

@@ -1,4 +1,3 @@
-/* prettier-ignore-start */
 /* eslint-disable */
 /**
  * Generated utilities for implementing server-side Convex query and mutation functions.
@@ -72,5 +71,4 @@ export const internalAction = internalActionGeneric;
  * @returns The wrapped endpoint function. Route a URL path to this function in `convex/http.js`.
  */
 export const httpAction = httpActionGeneric;
-/* prettier-ignore-end */
 //# sourceMappingURL=server.js.map

package/dist/esm/component/_generated/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../../src/component/_generated/server.js"],"names":[],"mappings":"AAAA,2BAA2B;AAE3B,oBAAoB;AACpB;;;;;;;GAOG;AAEH,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAEvB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,YAAY,CAAC;AAElC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,oBAAoB,CAAC;AAElD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,eAAe,CAAC;AAExC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,uBAAuB,CAAC;AAExD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,aAAa,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,qBAAqB,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,iBAAiB,CAAC;AAE5C,yBAAyB"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../../src/component/_generated/server.js"],"names":[],"mappings":"AAAA,oBAAoB;AACpB;;;;;;;GAOG;AAEH,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAEvB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,YAAY,CAAC;AAElC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,oBAAoB,CAAC;AAElD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,eAAe,CAAC;AAExC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,uBAAuB,CAAC;AAExD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,aAAa,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,qBAAqB,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,iBAAiB,CAAC"}

package/dist/esm/component/public.d.ts

@@ -7,4 +7,13 @@ export declare const add: import("convex/server").RegisteredMutation<"public", {
 export declare const count: import("convex/server").RegisteredQuery<"public", {
     name: string;
 }, Promise<number>>;
+export declare const rebalance: import("convex/server").RegisteredMutation<"public", {
+    shards?: number | undefined;
+    name: string;
+}, Promise<void>>;
+export declare const estimateCount: import("convex/server").RegisteredQuery<"public", {
+    shards?: number | undefined;
+    readFromShards?: number | undefined;
+    name: string;
+}, Promise<number>>;
 //# sourceMappingURL=public.d.ts.map

package/dist/esm/component/public.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../../src/component/public.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,eAAO,MAAM,GAAG;;;;iBAyBd,CAAC;AAEH,eAAO,MAAM,KAAK;;mBAUhB,CAAC"}
+{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../../src/component/public.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,eAAO,MAAM,GAAG;;;;iBAyBd,CAAC;AAEH,eAAO,MAAM,KAAK;;mBAUhB,CAAC;AAEH,eAAO,MAAM,SAAS;;;iBA2BpB,CAAC;AAEH,eAAO,MAAM,aAAa;;;;mBAsBxB,CAAC"}

package/dist/esm/component/public.js

@@ -39,4 +39,64 @@ export const count = query({
         return counters.reduce((sum, counter) => sum + counter.value, 0);
     },
 });
+export const rebalance = mutation({
+    args: { name: v.string(), shards: v.optional(v.number()) },
+    handler: async (ctx, args) => {
+        const counters = await ctx.db
+            .query("counters")
+            .withIndex("name", (q) => q.eq("name", args.name))
+            .collect();
+        const count = counters.reduce((sum, counter) => sum + counter.value, 0);
+        const shardCount = args.shards ?? DEFAULT_SHARD_COUNT;
+        const value = count / shardCount;
+        for (let i = 0; i < shardCount; i++) {
+            const shard = counters.find((c) => c.shard === i);
+            if (shard) {
+                await ctx.db.patch(shard._id, { value });
+            }
+            else {
+                await ctx.db.insert("counters", {
+                    name: args.name,
+                    value,
+                    shard: i,
+                });
+            }
+        }
+        const toDelete = counters.filter((c) => c.shard >= shardCount);
+        for (const counter of toDelete) {
+            await ctx.db.delete(counter._id);
+        }
+    },
+});
+export const estimateCount = query({
+    args: {
+        name: v.string(),
+        readFromShards: v.optional(v.number()),
+        shards: v.optional(v.number()),
+    },
+    handler: async (ctx, args) => {
+        const shardCount = args.shards ?? DEFAULT_SHARD_COUNT;
+        const readFromShards = Math.min(Math.max(1, args.readFromShards ?? 1), shardCount);
+        const shards = shuffle(Array.from({ length: shardCount }, (_, i) => i)).slice(0, readFromShards);
+        let readCount = 0;
+        for (const shard of shards) {
+            const counter = await ctx.db
+                .query("counters")
+                .withIndex("name", (q) => q.eq("name", args.name).eq("shard", shard))
+                .unique();
+            if (counter) {
+                readCount += counter.value;
+            }
+        }
+        return (readCount * shardCount) / readFromShards;
+    },
+});
+// Fisher-Yates shuffle
+function shuffle(array) {
+    for (let i = array.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [array[i], array[j]] = [array[j], array[i]];
+    }
+    return array;
+}
 //# sourceMappingURL=public.js.map

package/dist/esm/component/public.js.map

@@ -1 +1 @@
-{"version":3,"file":"public.js","sourceRoot":"","sources":["../../../src/component/public.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEtD,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAEtC,MAAM,CAAC,MAAM,GAAG,GAAG,QAAQ,CAAC;IAC1B,IAAI,EAAE;QACJ,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;QAChB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;QACjB,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;KAC/B;IACD,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE;IACjB,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,mBAAmB,CAAC,CAAC,CAAC;QAC/E,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,EAAE;aACzB,KAAK,CAAC,UAAU,CAAC;aACjB,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;aACpE,MAAM,EAAE,CAAC;QACZ,IAAI,OAAO,EAAE;YACX,MAAM,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE;gBAC9B,KAAK,EAAE,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK;aAClC,CAAC,CAAC;SACJ;aAAM;YACL,MAAM,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE;gBAC9B,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,KAAK;aACN,CAAC,CAAC;SACJ;IACH,CAAC;CACF,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,KAAK,GAAG,KAAK,CAAC;IACzB,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE;IAC1B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC3B,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,EAAE;aAC1B,KAAK,CAAC,UAAU,CAAC;aACjB,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;aACjD,OAAO,EAAE,CAAC;QACb,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,CAAC,GAAG,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACnE,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"public.js","sourceRoot":"","sources":["../../../src/component/public.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -7,7 +7,7 @@
     "email": "support@convex.dev",
     "url": "https://github.com/get-convex/sharded-counter/issues"
   },
-  "version": "0.1.3",
+  "version": "0.1.4",
   "license": "Apache-2.0",
   "keywords": [
     "convex",

package/src/client/index.ts

@@ -1,14 +1,20 @@
 import {
+  DocumentByName,
   Expand,
   FunctionReference,
   GenericDataModel,
   GenericMutationCtx,
   GenericQueryCtx,
+  TableNamesInDataModel,
 } from "convex/server";
 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 atomically.
+ */
+export class ShardedCounter<ShardsKey extends string> {
   /**
    * A sharded counter is a map from string -> counter, where each counter can
    * be incremented or decremented.
@@ -26,7 +32,7 @@ export class ShardedCounter<Shards extends Record<string, number>> {
    */
   constructor(
     private component: UseApi<typeof api>,
-    private options?: { shards?: Shards; defaultShards?: number }
+    private options?: { shards?: Record<ShardsKey, number>; defaultShards?: number }
   ) {}
   /**
    * Increase the counter for key `name` by `count`.
@@ -35,30 +41,94 @@ export class ShardedCounter<Shards extends Record<string, number>> {
    * @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>(
+  async add<Name extends string = ShardsKey>(
     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,
+      shards: this.shardsForKey(name),
     });
   }
+  /**
+   * Decrease the counter for key `name` by `count`.
+   */
+  async subtract<Name extends string = ShardsKey>(
+    ctx: RunMutationCtx,
+    name: Name,
+    count: number = 1
+  ) {
+    return this.add(ctx, name, -count);
+  }
+  /**
+   * Increment the counter for key `name` by 1.
+   */
+  async inc<Name extends string = ShardsKey>(ctx: RunMutationCtx, name: Name) {
+    return this.add(ctx, name, 1);
+  }
+  /**
+   * Decrement the counter for key `name` by 1.
+   */
+  async dec<Name extends string = ShardsKey>(ctx: RunMutationCtx, name: Name) {
+    return this.add(ctx, name, -1);
+  }
   /**
    * 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>(
+  async count<Name extends string = ShardsKey>(
     ctx: RunQueryCtx,
     name: Name
   ) {
     return ctx.runQuery(this.component.public.count, { name });
   }
+  /**
+   * Redistribute counts evenly across the counter's shards.
+   * 
+   * If there were more shards for this counter at some point, those shards
+   * will be removed.
+   * 
+   * If there were fewer shards for this counter, or if the random distribution
+   * of counts is uneven, the counts will be redistributed evenly.
+   * 
+   * This operation reads and writes all shards, so it can cause contention if
+   * called too often.
+   */
+  async rebalance<Name extends string = ShardsKey>(
+    ctx: RunMutationCtx,
+    name: Name,
+  ) {
+    await ctx.runMutation(this.component.public.rebalance, {
+      name,
+      shards: this.shardsForKey(name),
+    });
+  }
+  /**
+   * Estimate the count of a counter by only reading from a subset of shards,
+   * and extrapolating the total count.
+   * 
+   * After a `rebalance`, or if there were a lot of data points to yield a
+   * random distribution across shards, this should be a good approximation of
+   * the total count. If there are few data points, which are not evenly
+   * distributed across shards, this will be a poor approximation.
+   * 
+   * Use this to reduce contention when reading the counter.
+   */
+  async estimateCount<Name extends string = ShardsKey>(
+    ctx: RunQueryCtx,
+    name: Name,
+    readFromShards: number = 1,
+  ) {
+    return await ctx.runQuery(this.component.public.estimateCount, {
+      name,
+      shards: this.shardsForKey(name),
+      readFromShards,
+    });
+  }
   /**
    * 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
@@ -74,7 +144,7 @@ export class ShardedCounter<Shards extends Record<string, number>> {
    * });
    * ```
    */
-  for<Name extends string = keyof Shards & string>(name: Name) {
+  for<Name extends string = ShardsKey>(name: Name) {
     return {
       /**
        * Add `count` to the counter.
@@ -101,12 +171,70 @@ export class ShardedCounter<Shards extends Record<string, number>> {
        * contend with all mutations that update the counter for this key.
        */
       count: async (ctx: RunQueryCtx) => this.count(ctx, name),
+      /**
+       * Redistribute counts evenly across the counter's shards.
+       * 
+       * This operation reads and writes all shards, so it can cause contention
+       * if called too often.
+       */
+      rebalance: async (ctx: RunMutationCtx) => this.rebalance(ctx, name),
+      /**
+       * Estimate the counter by only reading from a subset of shards,
+       * and extrapolating the total count.
+       * 
+       * Use this to reduce contention when reading the counter.
+       */
+      estimateCount: async (ctx: RunQueryCtx, readFromShards: number = 1) =>
+        this.estimateCount(ctx, name, readFromShards),
     };
   }
+  trigger<
+    Ctx extends RunMutationCtx,
+    Name extends string = ShardsKey,
+  >(
+    name: Name,
+  ): Trigger<Ctx, GenericDataModel, TableNamesInDataModel<GenericDataModel>> {
+    return async (ctx, change) => {
+      if (change.operation === "insert") {
+        await this.inc(ctx, name);
+      } else if (change.operation === "delete") {
+        await this.dec(ctx, name);
+      }
+    };
+  }
+  private shardsForKey<Name extends string = ShardsKey>(name: Name) {
+    const explicitShards = this.options?.shards?.[name as string as ShardsKey];
+    return explicitShards ?? this.options?.defaultShards;
+  }
 }
 
 /* Type utils follow */
 
+export type Trigger<
+  Ctx,
+  DataModel extends GenericDataModel,
+  TableName extends TableNamesInDataModel<DataModel>,
+> = (ctx: Ctx, change: Change<DataModel, TableName>) => Promise<void>;
+
+export type Change<
+  DataModel extends GenericDataModel,
+  TableName extends TableNamesInDataModel<DataModel>,
+> = {
+  id: GenericId<TableName>;
+} & ({
+  operation: "insert";
+  oldDoc: null
+  newDoc: DocumentByName<DataModel, TableName>;
+} | {
+  operation: "update";
+  oldDoc: DocumentByName<DataModel, TableName>;
+  newDoc: DocumentByName<DataModel, TableName>;
+} | {
+  operation: "delete";
+  oldDoc: DocumentByName<DataModel, TableName>;
+  newDoc: null;
+});
+
 type RunQueryCtx = {
   runQuery: GenericQueryCtx<GenericDataModel>["runQuery"];
 };