kitcn 0.19.0 → 0.20.0

package/dist/{runtime-DmVSOe24.js → runtime-6DJxpDfb.js}

@@ -1512,7 +1512,7 @@ function aggregateNameFromNamespace(namespace) {
 async function insertHandler(ctx, args) {
 	const tree = await getOrCreateTree(ctx.db, args.namespace, DEFAULT_MAX_NODE_SIZE, true);
 	const summand = args.summand ?? 0;
-	const pushUp = await insertIntoNode(ctx, args.namespace, tree.root, {
+	const pushUp = await insertIntoNode(ctx, tree.maxNodeSize, tree.root, {
 		k: args.key,
 		v: args.value,
 		s: summand
@@ -1529,7 +1529,7 @@ async function insertHandler(ctx, args) {
 }
 async function deleteHandler(ctx, args) {
 	const tree = await getOrCreateTree(ctx.db, args.namespace, DEFAULT_MAX_NODE_SIZE, true);
-	await deleteFromNode(ctx, args.namespace, tree.root, args.key);
+	await deleteFromNode(ctx, tree.maxNodeSize, tree.root, args.key);
 	const root = await ctx.db.get(tree.root);
 	if (root.items.length === 0 && root.subtrees.length === 1) {
 		log(`collapsing root ${root._id} because its only child is ${root.subtrees[0]}`);
@@ -1538,13 +1538,12 @@ async function deleteHandler(ctx, args) {
 		await ctx.db.delete(root._id);
 	}
 }
-async function MAX_NODE_SIZE(ctx, namespace) {
-	return (await mustGetTree(ctx.db, namespace)).maxNodeSize;
+function assertMaxNodeSize(maxNodeSize) {
+	if (maxNodeSize % 2 !== 0 || maxNodeSize < 4) throw new Error("MAX_NODE_SIZE must be even and at least 4");
 }
-async function MIN_NODE_SIZE(ctx, namespace) {
-	const max = await MAX_NODE_SIZE(ctx, namespace);
-	if (max % 2 !== 0 || max < 4) throw new Error("MAX_NODE_SIZE must be even and at least 4");
-	return max / 2;
+function minNodeSizeFor(maxNodeSize) {
+	assertMaxNodeSize(maxNodeSize);
+	return maxNodeSize / 2;
 }
 async function aggregateBetweenHandler(ctx, args) {
 	const tree = await getTree(ctx.db, args.namespace);
@@ -1554,8 +1553,8 @@ async function aggregateBetweenHandler(ctx, args) {
 	};
 	return await aggregateBetweenInNode(ctx.db, tree.root, args.k1, args.k2);
 }
-async function filterBetween(db, node, k1, k2) {
-	const n = await db.get(node);
+async function filterBetween(db, node, k1, k2, preloaded) {
+	const n = preloaded ?? await db.get(node);
 	const included = [];
 	function includeSubtree(i, unboundedRight) {
 		const unboundedLeft = k1 === void 0 || included.length > 0;
@@ -1623,7 +1622,7 @@ async function offsetUntilHandler(ctx, args) {
 		namespace: args.namespace
 	})).count;
 }
-async function deleteFromNode(ctx, namespace, node, key) {
+async function deleteFromNode(ctx, maxNodeSize, node, key) {
 	let n = await ctx.db.get(node);
 	let foundItem = null;
 	let i = 0;
@@ -1659,13 +1658,13 @@ async function deleteFromNode(ctx, namespace, node, key) {
 		code: "DELETE_MISSING_KEY",
 		message: `key ${p(key)} not found in node ${n._id}`
 	});
-	const deleted = await deleteFromNode(ctx, namespace, n.subtrees[i], key);
+	const deleted = await deleteFromNode(ctx, maxNodeSize, n.subtrees[i], key);
 	if (!deleted) return null;
 	if (!foundItem) foundItem = deleted;
 	const newAggregate = n.aggregate && sub(n.aggregate, itemAggregate(deleted));
 	if (newAggregate) await ctx.db.patch(node, { aggregate: newAggregate });
 	const deficientSubtree = await ctx.db.get(n.subtrees[i]);
-	const minNodeSize = await MIN_NODE_SIZE(ctx, namespace);
+	const minNodeSize = minNodeSizeFor(maxNodeSize);
 	if (deficientSubtree.items.length < minNodeSize) {
 		log(`deficient subtree ${deficientSubtree._id}`);
 		if (i > 0) {
@@ -1751,26 +1750,28 @@ async function mergeNodes(db, parent, leftIndex) {
 	});
 	await db.delete(right._id);
 }
-async function negativeOffsetInNode(db, node, index, k1, k2) {
-	const filtered = await filterBetween(db, node, k1, k2);
+async function negativeOffsetInNode(db, node, index, k1, k2, preloaded) {
+	const filtered = await filterBetween(db, node, k1, k2, preloaded);
 	for (const included of filtered.reverse()) if (included.type === "item") {
 		if (index === 0) return included.item;
 		index -= 1;
 	} else {
-		const subtreeCount = (await nodeAggregate(db, await db.get(included.subtree))).count;
-		if (index < subtreeCount) return await negativeOffsetInNode(db, included.subtree, index);
+		const subtree = await db.get(included.subtree);
+		const subtreeCount = (await nodeAggregate(db, subtree)).count;
+		if (index < subtreeCount) return await negativeOffsetInNode(db, included.subtree, index, void 0, void 0, subtree);
 		index -= subtreeCount;
 	}
 	throw new ConvexError(`negative offset exceeded count by ${index} (in node ${node})`);
 }
-async function atOffsetInNode(db, node, index, k1, k2) {
-	const filtered = await filterBetween(db, node, k1, k2);
+async function atOffsetInNode(db, node, index, k1, k2, preloaded) {
+	const filtered = await filterBetween(db, node, k1, k2, preloaded);
 	for (const included of filtered) if (included.type === "item") {
 		if (index === 0) return included.item;
 		index -= 1;
 	} else {
-		const subtreeCount = (await nodeAggregate(db, await db.get(included.subtree))).count;
-		if (index < subtreeCount) return await atOffsetInNode(db, included.subtree, index);
+		const subtree = await db.get(included.subtree);
+		const subtreeCount = (await nodeAggregate(db, subtree)).count;
+		if (index < subtreeCount) return await atOffsetInNode(db, included.subtree, index, void 0, void 0, subtree);
 		index -= subtreeCount;
 	}
 	throw new ConvexError(`offset exceeded count by ${index} (in node ${node})`);
@@ -1812,7 +1813,7 @@ function accumulate(nums) {
 		sum: 0
 	});
 }
-async function insertIntoNode(ctx, namespace, node, item) {
+async function insertIntoNode(ctx, maxNodeSize, node, item) {
 	const n = await ctx.db.get(node);
 	let i = 0;
 	for (; i < n.items.length; i++) {
@@ -1820,31 +1821,41 @@ async function insertIntoNode(ctx, namespace, node, item) {
 		if (compare === -1) break;
 		if (compare === 0) throw new ConvexError(`key ${p(item.k)} already exists in node ${n._id}`);
 	}
+	let nextItems = n.items;
+	let nextSubtrees = n.subtrees;
 	if (n.subtrees.length > 0) {
-		const pushUp = await insertIntoNode(ctx, namespace, n.subtrees[i], item);
-		if (pushUp) await ctx.db.patch(node, {
-			items: [
+		const pushUp = await insertIntoNode(ctx, maxNodeSize, n.subtrees[i], item);
+		if (pushUp) {
+			nextItems = [
 				...n.items.slice(0, i),
 				pushUp.item,
 				...n.items.slice(i)
-			],
-			subtrees: [
+			];
+			nextSubtrees = [
 				...n.subtrees.slice(0, i),
 				pushUp.leftSubtree,
 				pushUp.rightSubtree,
 				...n.subtrees.slice(i + 1)
-			]
-		});
-	} else await ctx.db.patch(node, { items: [
+			];
+		}
+	} else nextItems = [
 		...n.items.slice(0, i),
 		item,
 		...n.items.slice(i)
-	] });
+	];
 	const newAggregate = n.aggregate && add(n.aggregate, itemAggregate(item));
-	if (newAggregate) await ctx.db.patch(node, { aggregate: newAggregate });
-	const newN = await ctx.db.get(node);
-	const maxNodeSize = await MAX_NODE_SIZE(ctx, namespace);
-	const minNodeSize = await MIN_NODE_SIZE(ctx, namespace);
+	const nodePatch = {};
+	if (nextItems !== n.items) nodePatch.items = nextItems;
+	if (nextSubtrees !== n.subtrees) nodePatch.subtrees = nextSubtrees;
+	if (newAggregate) nodePatch.aggregate = newAggregate;
+	if (Object.keys(nodePatch).length > 0) await ctx.db.patch(node, nodePatch);
+	const newN = {
+		...n,
+		items: nextItems,
+		subtrees: nextSubtrees,
+		aggregate: newAggregate ?? n.aggregate
+	};
+	const minNodeSize = minNodeSizeFor(maxNodeSize);
 	if (newN.items.length > maxNodeSize) {
 		if (newN.items.length !== maxNodeSize + 1 || newN.items.length !== 2 * minNodeSize + 1) throw new Error(`bad ${newN.items.length}`);
 		log(`splitting node ${newN._id} at ${newN.items[minNodeSize].k}`);
@@ -1889,6 +1900,7 @@ async function getOrCreateTree(db, namespace, maxNodeSize, rootLazy) {
 	const originalTree = await getTree(db, namespace);
 	const aggregateName = aggregateNameFromNamespace(namespace);
 	if (originalTree) {
+		assertMaxNodeSize(originalTree.maxNodeSize);
 		if (originalTree.aggregateName !== aggregateName) {
 			await db.patch(originalTree._id, { aggregateName });
 			return {
@@ -1906,7 +1918,7 @@ async function getOrCreateTree(db, namespace, maxNodeSize, rootLazy) {
 			sum: 0
 		}
 	});
-	const effectiveMaxNodeSize = maxNodeSize ?? await MAX_NODE_SIZE({ db }, void 0) ?? DEFAULT_MAX_NODE_SIZE;
+	const effectiveMaxNodeSize = maxNodeSize ?? (await mustGetTree(db, void 0)).maxNodeSize;
 	const effectiveRootLazy = rootLazy ?? await isRootLazy(db, void 0) ?? true;
 	const id = await db.insert(AGGREGATE_TREE_TABLE, {
 		aggregateName,
@@ -1915,7 +1927,7 @@ async function getOrCreateTree(db, namespace, maxNodeSize, rootLazy) {
 		namespace
 	});
 	const newTree = await db.get(id);
-	await MIN_NODE_SIZE({ db }, namespace);
+	assertMaxNodeSize(effectiveMaxNodeSize);
 	if (effectiveRootLazy) await db.patch(root, { aggregate: void 0 });
 	return newTree;
 }
@@ -1930,6 +1942,19 @@ async function deleteTreeNodes(db, node) {
 	for (const subtree of current.subtrees) await deleteTreeNodes(db, subtree);
 	await db.delete(node);
 }
+/**
+* Deletes up to `limit` namespace trees belonging to one aggregate, returning
+* true once none are left. Unlike `clearTree` this does not recreate the tree,
+* so a caller can drain every namespace across several transactions.
+*/
+async function deleteTreesHandler(ctx, args) {
+	const trees = await ctx.db.query(AGGREGATE_TREE_TABLE).withIndex("by_aggregate_name", (q) => q.eq("aggregateName", args.aggregateName)).take(args.limit);
+	for (const tree of trees) {
+		await deleteTreeNodes(ctx.db, tree.root);
+		await ctx.db.delete(tree._id);
+	}
+	return trees.length === 0;
+}
 async function clearTree(db, args) {
 	const tree = await getTree(db, args.namespace);
 	let existingRootLazy = true;
@@ -2319,6 +2344,17 @@ var Aggregate = class {
 			rootLazy: opts[0]?.rootLazy
 		});
 	}
+	/**
+	* Deletes up to `limit` namespace trees without recreating them. Returns true
+	* once this aggregate owns no trees, so callers can drain every namespace
+	* across several mutations instead of walking them all in one.
+	*/
+	async deleteTrees(ctx, limit) {
+		return deleteTreesHandler({ db: ctx.db }, {
+			aggregateName: this.aggregateName,
+			limit
+		});
+	}
 	async makeRootLazy(ctx, namespace) {
 		const tree = await getOrCreateTree(ctx.db, namespaceForArg(this.aggregateName, { namespace }));
 		await ctx.db.patch(tree.root, { aggregate: void 0 });

package/dist/watcher.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as generateMeta, c as PARSE_SNAPSHOT_SUFFIX, i as resolveConfiguredBackend, n as withLocalCodegenEnv, o as getConvexConfig, r as loadCliConfig, s as logger } from "./local-env-DykABjCt.mjs";
+import { a as generateMeta, c as PARSE_SNAPSHOT_SUFFIX, i as resolveConfiguredBackend, n as withLocalCodegenEnv, o as getConvexConfig, r as loadCliConfig, s as logger } from "./local-env-yFKub75x.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 

package/dist/{where-clause-compiler-CmBz9CWA.d.ts → where-clause-compiler-BGBNBNit.d.ts}

@@ -4390,26 +4390,26 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "status";
         };
       };
-      kind: ConvexTextBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
+      cursor: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "aggregate_state";
         };
       } & {
         _: {
-          fieldName: "kind";
+          fieldName: "cursor";
         };
       };
-      cursor: ConvexTextBuilderInitial<""> & {
+      kind: ConvexTextBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
         _: {
           tableName: "aggregate_state";
         };
       } & {
         _: {
-          fieldName: "cursor";
+          fieldName: "kind";
         };
       };
       updatedAt: ConvexNumberBuilderInitial<""> & {
@@ -4526,6 +4526,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
     by_creation_time: ["_creationTime"];
     by_kind_table_index: ["kind", "tableKey", "indexName", "_creationTime"];
     by_kind_status: ["kind", "status", "_creationTime"];
+    by_table_status: ["tableKey", "status", "_creationTime"];
   }, {}, {}, {}>;
 }>, SchemaExtension<{
   readonly migration_state: ConvexTableWithColumns<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitcn",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "kitcn - React Query integration and CLI tools for Convex",
   "keywords": [
     "convex",

package/skills/kitcn/references/features/aggregates.md

@@ -54,7 +54,7 @@ Windowed count: `count({ where, orderBy, skip, take, cursor })` counts rows with
 | Error                      | Cause                                        |
 | -------------------------- | -------------------------------------------- |
 | `COUNT_NOT_INDEXED`        | No `aggregateIndex` matches the filter shape |
-| `COUNT_FILTER_UNSUPPORTED` | Uses unsupported operators                   |
+| `COUNT_FILTER_UNSUPPORTED` | Unsupported operators, or a range count/aggregate over `aggregateWorkBudget` work units |
 | `COUNT_INDEX_BUILDING`     | Index still backfilling                      |
 | `COUNT_RLS_UNSUPPORTED`    | Called in RLS-restricted context             |
 
@@ -310,6 +310,15 @@ If rank or aggregate state gets out of sync:
 kitcn aggregate rebuild
 ```
 
+Rebuild clears stored state in scheduled batches. Indexes report `CLEARING`
+while draining and `BUILDING` while recomputing; wait for `READY`.
+Writes targeting a declared index in `CLEARING` fail before the document write;
+retry them after the index advances to `BUILDING` or `READY`.
+Automatic pruning follows aggregate lifecycle state, so kickoff reads stay
+bounded as the backing tables grow. For state-less storage, call
+`aggregateBackfill` in `prune` mode with exact `tableName` and `indexName`
+arguments.
+
 ## When to Use
 
 | Need                   | Use                                                             |