@convex-dev/sharded-counter 0.1.3 → 0.1.5

package/README.md

@@ -2,15 +2,15 @@
 
 [![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.
 
 Since it's built on Convex, everything is automatically consistent, reactive,
-and cached.
+and cached. Since it's built with [Components](https://convex.dev/components),
+the operations are isolated and increment/decrement are atomic even if run in
+parallel.
 
 For example, if you want to display
 [one million checkboxes](https://en.wikipedia.org/wiki/One_Million_Checkboxes)
@@ -95,14 +95,18 @@ Once you have a `ShardedCounter`, there are a few methods you can use to update
 the counter for a key in a mutation or action.
 
 ```ts
-await counter.add(ctx, "checkboxes"); // increment
-await counter.add(ctx, "checkboxes", -5); // decrement by 5
+await counter.add(ctx, "checkboxes", 5); // increment by 5
+await counter.inc(ctx, "checkboxes"); // increment by 1
+await counter.subtract(ctx, "checkboxes", 5); // decrement by 5
+await counter.dec(ctx, "checkboxes"); // decrement by 1
+await counter.reset(ctx, "checkboxes"); // reset to 0
 
 const numCheckboxes = counter.for("checkboxes");
 await numCheckboxes.inc(ctx); // increment
 await numCheckboxes.dec(ctx); // decrement
 await numCheckboxes.add(ctx, 5); // add 5
 await numCheckboxes.subtract(ctx, 5); // subtract 5
+await numCheckboxes.reset(ctx); // reset to 0
 ```
 
 And you can read the counter's value in a query, mutation, or action.
@@ -141,7 +145,7 @@ Or by setting a default that applies to all keys not specified in `shards`:
 ```ts
 const counter = new ShardedCounter(components.shardedCounter, {
   shards: { checkboxes: 100 },
-  defaultShards: 20,
+  defaultShards: 8,
 });
 ```
 
@@ -158,9 +162,118 @@ const friendCounts = new ShardedCounter<Record<Id<"users">, number>>(
 );
 
 // Decrement a user's friend count by 1
-await friendsCount.add(ctx, userId, -1);
+await friendsCount.dec(ctx, userId);
+```
+
+## Reduce contention on reads
+
+Reading the count with `counter.count(ctx, "checkboxes")` reads from all shards
+to get an accurate count. This takes a read dependency on all shard documents.
+
+- In a query subscription, that means any change to the counter causes the query
+  to rerun.
+- In a mutation, that means any modification to the counter causes an
+  [OCC](https://docs.convex.dev/error#1) conflict.
+
+You can reduce contention by estimating the count: read from a smaller number
+of shards and extrapolate based on the total number of shards.
+
+```ts
+const estimatedCheckboxCount = await counter.estimateCount(ctx, "checkboxes");
+```
+
+By default, this reads from a single random shard and multiplies by the total
+number of shards to form an estimate. You can improve the estimate by reading
+from more shards, at the cost of more contention:
+
+```ts
+const estimateFromThree = await counter.estimateCount(ctx, "checkboxes", 3);
+```
+
+If the counter was accumulated from many
+small `counter.inc` and `counter.dec` calls, then they should be uniformly
+distributed across the shards, so estimated counts will be accurate.
+
+In some cases the counter will not be evenly distributed:
+
+- If the counter was accumulated from few operations
+- If some operations were `counter.add`s or `counter.subtract`s with large
+  values, because each operation only changes a single shard
+- If the number of shards changed
+
+In these cases, the count might not be evenly distributed across the shards.
+To repair such cases, you can call:
+
+```ts
+await counter.rebalance(ctx, "checkboxes");
+```
+
+Which will even out the count across shards.
+
+You may change the number of shards for a key, by changing the second argument
+to the `ShardedCounter` constructor. If you decrease the number of shards,
+you will be left with extra shards that won't be written to but are still
+read when computing `count`.
+In this case, you should call `counter.rebalance` to delete
+the extraneous shards.
+
+NOTE: `counter.rebalance` reads and writes all shards, so it could cause
+more OCCs, and it's recommended you call it sparingly, from the Convex dashboard
+or from an infrequent cron.
+
+NOTE: counts are floats, and floating point arithmetic isn't infinitely
+precise. Even if you always add and subtract integers, you may get a fractional
+counts, especially if you use `estimateCount` or `rebalance`.
+Values distributed across shards may be added in different combinations, and
+[floating point arithmetic isn't associative](https://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html).
+You can use `Math.round` to ensure your final count is an integer, if
+desired.
+
+## Counting documents in a table
+
+Often you want to use a sharded counter to track how many documents are in a
+table.
+
+> If you want more than just a count, take a look at the
+> [Aggregate component](https://www.npmjs.com/package/@convex-dev/aggregate).
+
+There are three ways to go about keeping a count in sync with a table:
+
+1. Be careful to always update the aggregate in any mutation that inserts or
+   deletes from the table.
+2. \[Recommended\] Place all writes to a table in separate TypeScript functions,
+   and always call these functions from mutations instead of writing to the db
+   directly. This method is recommended, because it encapsulates the logic for
+   updating a table, while still keeping all operations explicit. For example,
+
+```ts
+// Example of a mutation that calls `insertUser`.
+export const insertPair = mutation(async (ctx) => {
+  ...
+  await insertUser(ctx, user1);
+  await insertUser(ctx, user2);
+});
+
+// All inserts to the "users" table go through this function.
+async function insertUser(ctx, user) {
+  await ctx.db.insert("users", user);
+  await counter.inc(ctx, "users");
+}
+```
+
+3. Register a [Trigger](https://www.npmjs.com/package/convex-helpers#triggers),
+   which automatically runs code when a mutation changes the
+   data in a table.
+
+```ts
+// Triggers hook up writes to the table to the ShardedCounter.
+const triggers = new Triggers<DataModel>();
+triggers.register("mytable", counter.trigger("mycounter"));
+export const mutation = customMutation(rawMutation, customCtx(triggers.wrapDB));
 ```
 
+The [insertUserWithTrigger](example/convex/example.ts) mutation uses a trigger.
+
 ## Backfilling an existing count
 
 If you want to count items like documents in a table, you may already have
@@ -174,6 +287,22 @@ 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.
 
+### Simple backfill: if table is append-only
+
+See example code at the bottom of
+[example/convex/example.ts](example/convex/example.ts).
+
+Walkthrough of steps:
+
+1. Change live writes to update the counter. In the example, you would be
+   changing `insertUserBeforeBackfill` to be implemented as
+   `insertUserAfterBackfill`.
+2. Write a backfill that counts documents that were created before the code from
+   (1) deployed. In the example, this would be `backfillOldUsers`.
+3. Run `backfillOldUsers` from the dashboard.
+
+### Complex backfill: if documents may be deleted
+
 See example code at the bottom of
 [example/convex/example.ts](example/convex/example.ts).
 

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

@@ -1,9 +1,12 @@
-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?;
     /**
      * A sharded counter is a map from string -> counter, where each counter can
      * be incremented or decremented.
@@ -20,9 +23,11 @@ export declare class ShardedCounter<Shards extends Record<string, number>> {
      *   keys not in `options.shards`.
      */
     constructor(component: UseApi<typeof api>, options?: {
-        shards?: Shards | undefined;
-        defaultShards?: number | undefined;
-    } | undefined);
+        shards?: Partial<Record<ShardsKey, number>>;
+        defaultShards?: number;
+    });
+    private shardsForKey;
+    private stickyShard;
     /**
      * Increase the counter for key `name` by `count`.
      * If `count` is negative, the counter will decrease.
@@ -30,14 +35,57 @@ 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 ShardsKey>(ctx: RunMutationCtx, name: Name, count?: number): Promise<void>;
+    /**
+     * Decrease the counter for key `name` by `count`.
+     */
+    subtract<Name extends ShardsKey>(ctx: RunMutationCtx, name: Name, count?: number): Promise<void>;
+    /**
+     * Increment the counter for key `name` by 1.
+     */
+    inc<Name extends ShardsKey>(ctx: RunMutationCtx, name: Name): Promise<void>;
+    /**
+     * Decrement the counter for key `name` by 1.
+     */
+    dec<Name extends ShardsKey>(ctx: RunMutationCtx, name: Name): Promise<void>;
     /**
      * 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 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 ShardsKey>(ctx: RunMutationCtx, name: Name): Promise<void>;
+    /**
+     * Clear the counter for key `name`.
+     *
+     * @param name The key to clear the counter for.
+     */
+    reset<Name extends 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 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,23 +101,23 @@ export declare class ShardedCounter<Shards extends Record<string, number>> {
      * });
      * ```
      */
-    for<Name extends string = keyof Shards & string>(name: Name): {
+    for<Name extends ShardsKey>(name: Name): {
         /**
          * Add `count` to the counter.
          */
-        add: (ctx: RunMutationCtx, count?: number) => Promise<null>;
+        add: (ctx: RunMutationCtx, count?: number) => Promise<void>;
         /**
          * Subtract `count` from the counter.
          */
-        subtract: (ctx: RunMutationCtx, count?: number) => Promise<null>;
+        subtract: (ctx: RunMutationCtx, count?: number) => Promise<void>;
         /**
          * Increment the counter by 1.
          */
-        inc: (ctx: RunMutationCtx) => Promise<null>;
+        inc: (ctx: RunMutationCtx) => Promise<void>;
         /**
          * Decrement the counter by 1.
          */
-        dec: (ctx: RunMutationCtx) => Promise<null>;
+        dec: (ctx: RunMutationCtx) => Promise<void>;
         /**
          * Get the current value of the counter.
          *
@@ -77,8 +125,43 @@ 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>;
+        /**
+         * Reset the counter for this key.
+         */
+        reset: (ctx: RunMutationCtx) => Promise<void>;
+        /**
+         * 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 ShardsKey>(name: Name): Trigger<Ctx, GenericDataModel, TableNamesInDataModel<GenericDataModel>>;
 }
+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/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;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/commonjs/client/index.js

@@ -1,6 +1,9 @@
+/**
+ * A sharded counter is a map from string -> counter, where each counter can
+ * be incremented or decremented atomically.
+ */
 export class ShardedCounter {
     component;
-    options;
     /**
      * A sharded counter is a map from string -> counter, where each counter can
      * be incremented or decremented.
@@ -18,8 +21,17 @@ export class ShardedCounter {
      */
     constructor(component, options) {
         this.component = component;
-        this.options = options;
+        this.stickyShard = {};
+        const defaultShards = options?.defaultShards;
+        this.shardsForKey = (name) => {
+            const explicitShards = options?.shards?.[name];
+            return explicitShards ?? defaultShards;
+        };
     }
+    shardsForKey;
+    // Keep track of the shard for each key, so multiple mutations on the same key
+    // will use the same shard.
+    stickyShard;
     /**
      * Increase the counter for key `name` by `count`.
      * If `count` is negative, the counter will decrease.
@@ -28,12 +40,31 @@ 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, {
+        const shard = await ctx.runMutation(this.component.public.add, {
             name,
             count,
-            shards,
+            shard: this.stickyShard?.[name],
+            shards: this.shardsForKey(name),
         });
+        this.stickyShard[name] = shard;
+    }
+    /**
+     * 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 +75,50 @@ 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),
+        });
+    }
+    /**
+     * Clear the counter for key `name`.
+     *
+     * @param name The key to clear the counter for.
+     */
+    async reset(ctx, name) {
+        await ctx.runMutation(this.component.public.reset, { 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,6 +159,34 @@ export class ShardedCounter {
              * contend with all mutations that update the counter for this key.
              */
             count: async (ctx) => this.count(ctx, name),
+            /**
+             * Reset the counter for this key.
+             */
+            reset: async (ctx) => this.reset(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);
+            }
         };
     }
 }

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;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/commonjs/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/commonjs/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/commonjs/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/commonjs/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/commonjs/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/commonjs/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/commonjs/component/public.d.ts

@@ -1,10 +1,23 @@
 export declare const DEFAULT_SHARD_COUNT = 16;
 export declare const add: import("convex/server").RegisteredMutation<"public", {
+    shard?: number | undefined;
     shards?: number | undefined;
     name: string;
     count: number;
-}, Promise<void>>;
+}, Promise<number>>;
 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 reset: import("convex/server").RegisteredMutation<"public", {
+    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/commonjs/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;;;;;mBA6Bd,CAAC;AAEH,eAAO,MAAM,KAAK;;mBAUhB,CAAC;AAEH,eAAO,MAAM,SAAS;;;iBA2BpB,CAAC;AAEH,eAAO,MAAM,KAAK;;iBAWhB,CAAC;AAEH,eAAO,MAAM,aAAa;;;;mBA2BxB,CAAC"}