Mikec/visual examples #44

mikecann · 2025-08-06T02:51:34Z

In this PR I am adding a visual frontend to the example so users can go ahead and play around with it.

In a future PR (if all goes well with this one). I will get the example hosted so it can be linked to from this repo so people dont have to clone this repo to try out the examples.

This is quite a large PR where I have tried to confine everything to the example directory. I did however need to add a couple more queries to the "inspect" file in the root, this is so I can get more data to inspect the btrees.

I will be using these visualisations as the basis for a video on the Aggregate component that I can currently working on.

pkg-pr-new · 2025-08-12T06:49:22Z

Open in StackBlitz

npm i https://pkg.pr.new/get-convex/aggregate/@convex-dev/aggregate@44

commit: b2f77cc

ianmacartney

Looks good overall! Good to deploy. A few things to clean up before merging, but no need for second review unless you want more eyes

ianmacartney · 2025-08-13T02:16:28Z

example/.gitignore

+
+# Ignored for the template, you probably want to remove it:
+package-lock.json


Suggested change

# Ignored for the template, you probably want to remove it:

package-lock.json

ianmacartney · 2025-08-13T02:17:06Z

example/README.md

+npm install
+npm run build
+cd example
+npm install


Suggested change

npm install

npm run build

cd example

npm install

npm run setup

ianmacartney · 2025-08-13T02:23:42Z

src/component/inspect.ts

+export const listTrees = query({
+  args: {
+    take: v.optional(v.number()),
+  },
+  returns: v.array(
+    v.object({
+      root: v.id("btreeNode"),
+      namespace: v.optional(v.any()),
+      maxNodeSize: v.number(),
+      _id: v.id("btree"),
+      _creationTime: v.number(),
+    })
+  ),
+  handler: async (ctx, args) => {
+    const values = await ctx.db.query("btree").take(args.take ?? 100);
+    return values;
+  },
+});
+
+export const listTreeNodes = query({
+  args: {
+    take: v.optional(v.number()),
+  },
+  returns: v.array(
+    v.object({
+      items: v.array(itemValidator),
+      subtrees: v.array(v.id("btreeNode")),
+      aggregate: v.optional(aggregate),
+      _id: v.id("btreeNode"),
+      _creationTime: v.number(),
+    })
+  ),
+  handler: async (ctx, args) => {
+    const values = await ctx.db.query("btreeNode").take(args.take ?? 100);
+    return values;
+  },
+});


nit: One risk here is that the returns validator is tightly coupled to the component fields. We could use the ...schema.tables.btreeNode.validator.fields trick. The convex-helpers doc(schema, "btreeNode") helper would also be handy here. We could alternatively not specify the return validator to not have folks rely on it tightly - it'd be v.any?

I had a thought the other day that the crud helper could be really handy for components to avoid this boilerplate for basic get/list.

ye I was running into strange typing errors when using ...schema.tables.btreeNode.validator.fields ill try again

ianmacartney · 2025-08-13T02:25:03Z

package.json

@@ -22,8 +22,8 @@
    "setup": "npm i && npm run build && cd example && npm i && npx convex dev --once",
    "build:watch": "cd src && npx chokidar -d 1000 '../tsconfig.json' '**/*.ts' -c 'npm run build' --initial",
    "build": "npm run build:esm && npm run build:cjs",
-    "build:esm": "tsc --project ./esm.json && echo '{\\n  \"type\": \"module\"\\n}' > dist/esm/package.json",
-    "build:cjs": "tsc --project ./commonjs.json && echo '{\\n  \"type\": \"commonjs\"\\n}' > dist/commonjs/package.json",
+    "build:esm": "tsc --project ./esm.json && node -e \"require('fs').writeFileSync('dist/esm/package.json', JSON.stringify({type:'module'}))\"",


I wonder if we'll even need this package.json writing when we drop cjs targets (we've done that already for other components)

ianmacartney · 2025-08-13T02:33:25Z

example/convex/crons.ts

+import { internalMutation } from "./_generated/server";
+import { v } from "convex/values";
+
+export const resetAndSeed = internalMutation({


if this is being called from the hosted demo, and is doing a collect on every table to delete them, then I'm worried it'll run into the limits. For synchronous, you could have it be an action that calls actions that do deletes in batches, or do it asynchronously, where it paginates each table recursively and seeds afterwards. Or each reset could return if they were "done" and if not, it could bail out and schedule itself until they're all fully deleted before seeding? the last one might be easiest - each .collect turning into a .take(1000), say

ye fair enough, I did think about that but forgot to come back to it :P

ianmacartney · 2025-08-13T02:37:22Z

example/convex/photos.ts

+    const allPhotos = await ctx.db.query("photos").collect();
+    const albumNames = [...new Set(allPhotos.map((photo) => photo.album))];


FYI the .distinct on the streams helper would be useful here. then it could even be paginated, though that's not necessary here

this was the original code from the example I think. Ye I think ill keep it simpler for now by not introducing the streams concept

ianmacartney · 2025-08-13T02:38:19Z

example/convex/photos.ts

+});
+
+/**
+ * Get all available albums - useful for the UI


Maybe we drop the UI-oriented features lower than the illustrative ones?

yep fair enough

ianmacartney · 2025-08-13T02:39:09Z

example/convex/photos.ts

@@ -78,6 +104,14 @@ export const pageOfPhotos = query({
  },
  returns: v.array(v.string()),
  handler: async (ctx, { offset, numItems, album }) => {
+    // Check if the album has any photos first


what happens if we don't do this? does it throw for offset of 0?

yes I think it did, maybe it shouldnt?

ianmacartney · 2025-08-13T02:39:52Z

example/convex/shuffle.ts

+  query,
+  internalMutation,
+  MutationCtx,
+} from "../../example/convex/_generated/server";


I'm seeing a lot of ../../example/convex that should just be ./ -- what's that about?

ianmacartney · 2025-08-13T02:41:49Z

example/convex/shuffle.ts

@@ -18,25 +23,26 @@ const randomize = new TableAggregate<{
  sortKey: () => null,
 });

+const _addMusic = async (ctx: MutationCtx, { title }: { title: string }) => {


Suggested change

const _addMusic = async (ctx: MutationCtx, { title }: { title: string }) => {

async function addMusicHandler(ctx: MutationCtx, { title }: { title: string }) {

then you can define it below the addMusic const, so it visually flows / args are right there.

mikecann added 30 commits August 1, 2025 10:43

wip

7893a4a

wip adding a vite project

57497be

fixed quotes issues

268cb77

fixed typechecking failing on tests by excluding

9a20ce8

using mantine instead of tailwind

24d23dc

wip

5cf57fa

wip example ui

8f2c328

fixing error in this example

3b01e65

wip design

3b7eae2

added some nicer styling

989107f

wip

efc2d90

tidy

7295039

responsive stats page

8b9282b

fixed sidebar

8a9d6e9

better styles

f99bb01

wip

17e8c62

wip resetting

46c243a

clearing issue?

451cbce

tests pass but ts failing

b6359f5

removing any

6ec7a5c

fixed tests

d27f76a

added a couple of basic tests

639b40e

replicated the clearAll issue

acc1fc2

fixed clear issue

f763dc5

tidy tests a bit more

d836909

Merge branch 'mikec/fixing-clearAll' into mikec/visual-examples

b8405ed

tidied up vron

e7cee5f

improved photos examepl

1e053a5

improved shuffle example

05e2867

wip baseline tests

aa27981

mikecann added 18 commits August 6, 2025 11:07

fixed uneaven header

7a48628

split sections up a bit

c60d9f3

paginated leaderbaord

787fe66

better leaderboard layout

bed4d38

small refactors

455e13d

suffle page aside

1f032a7

better splitting up of the components with asides

66ddd9f

bounds optional

9339ee1

tidy up the page lookup

7d6f1f9

tidied up a couple of things

fc5547d

also allowing editing on the leaderboard rows

4737ea5

polishing with a convex logo

32059b3

removing the index and using triggers

30b0c51

added some more comments

6c29eab

better variable names

d0b495a

fixed example tests

ccd3b8d

Merge branch 'main' into mikec/visual-examples

ccddc39

fixed npm install

31b4816

mikecann marked this pull request as ready for review August 12, 2025 06:50

added thumb to readme

28f5483

ianmacartney approved these changes Aug 13, 2025

View reviewed changes

mikecann added 7 commits August 13, 2025 11:17

removed package lock as suggested

7487b55

fixing setup script in the example

d333e81

using the table validator instead

1f99230

preventing the resetAndSeed from potentially timing out

f122d9b

lowered ui function

73f1d4b

simplified imports

5946457

nicer flowing of code

b2f77cc

mikecann merged commit ff18253 into main Aug 13, 2025
2 checks passed


		# Ignored for the template, you probably want to remove it:
		package-lock.json

		const allPhotos = await ctx.db.query("photos").collect();
		const albumNames = [...new Set(allPhotos.map((photo) => photo.album))];

	const _addMusic = async (ctx: MutationCtx, { title }: { title: string }) => {
	async function addMusicHandler(ctx: MutationCtx, { title }: { title: string }) {

Mikec/visual examples #44

Mikec/visual examples #44

Uh oh!

Conversation

mikecann commented Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ianmacartney left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mikecann Aug 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mikecann commented Aug 6, 2025 •

edited

Loading

pkg-pr-new bot commented Aug 12, 2025 •

edited

Loading

mikecann Aug 13, 2025 •

edited

Loading