appflare 0.2.40 → 0.2.42

package/Documentation.md

@@ -164,6 +164,7 @@ export const listPostsPage = query({
 						},
 					}
 				: {},
+			orderBy: { column: "id", direction: "asc" },
 			limit: args.pageSize,
 			with: {
 				owner: true,
@@ -250,8 +251,8 @@ export const nearbyPlaygroundItems = query({
 					},
 					latitudeField: "latitude",
 					longitudeField: "longitude",
-					$gte: 0,
-					$lt: args.radiusMeters,
+					gte: 0,
+					lt: args.radiusMeters,
 				},
 				isActive: {
 					eq: true,
@@ -268,7 +269,69 @@ export const nearbyPlaygroundItems = query({
 });
 ```
 
-#### E) Complex production-style query (similar to `db-features`)
+#### F) Query with `orderBy`
+
+The `orderBy` field accepts an object or array of objects with `column` and optional `direction`:
+
+```ts
+import { query } from "../../_generated/handlers";
+import * as z from "zod";
+
+export const getTopUsers = query({
+	args: {
+		minScore: z.number().optional(),
+		limit: z.number().int().min(1).max(100).default(10),
+	},
+	handler: async (ctx, args) => {
+		return ctx.db.users.findMany({
+			where: args.minScore ? { score: { gte: args.minScore } } : {},
+			orderBy: { column: "score", direction: "desc" },
+			limit: args.limit,
+		});
+	},
+});
+```
+
+Multiple sort keys are supported with an array:
+
+```ts
+orderBy: [
+	{ column: "score", direction: "desc" },
+	{ column: "name", direction: "asc" },
+],
+```
+
+#### G) Array column operators (`includes`, `includesAny`, `length`)
+
+For JSON array columns, use array-specific operators:
+
+```ts
+import { query } from "../../_generated/handlers";
+import * as z from "zod";
+
+export const findProducts = query({
+	args: {
+		color: z.string().optional(),
+		tags: z.array(z.string()).optional(),
+		minTagCount: z.number().int().optional(),
+	},
+	handler: async (ctx, args) => {
+		return ctx.db.products.findMany({
+			where: {
+				...(args.tags ? { tags: { includes: args.tags } } : {}),
+				...(args.minTagCount ? { tags: { length: args.minTagCount } } : {}),
+			},
+		});
+	},
+});
+```
+
+- `includes` — row's array must contain **all** specified values
+- `includesAny` — row's array must contain **at least one** of the specified values
+- `length` — matches the array length exactly
+- `eq` / `ne` — exact match on the whole JSON array
+
+#### H) Complex production-style query (similar to `db-features`)
 
 ```ts
 import { query } from "../../_generated/handlers";
@@ -326,8 +389,11 @@ export const queryDashboardData = query({
 - Start with one root query and compose aggregates/relations progressively.
 - Prefer server-side filtering in `where` instead of filtering on frontend.
 - For heavy queries, add `limit`, cursor args, and response metadata (`nextCursor`, `hasMore`).
+- Use `orderBy` with cursor-based pagination to ensure deterministic ordering across pages.
 
-### 3.2 Mutation handler example
+### 3.2 Mutation handler examples
+
+#### Insert
 
 ```ts
 import { mutation } from "../../_generated/handlers";
@@ -352,6 +418,37 @@ export const createPost = mutation({
 });
 ```
 
+#### Upsert
+
+```ts
+import { mutation } from "../../_generated/handlers";
+import * as z from "zod";
+
+export const upsertPost = mutation({
+	args: {
+		slug: z.string().min(1),
+		title: z.string().min(1),
+	},
+	handler: async (ctx, args) => {
+		const result = await ctx.db.posts.upsert({
+			values: {
+				slug: args.slug,
+				title: args.title,
+				ownerId: "some-user-id",
+			},
+			target: "slug",
+			set: { title: args.title },
+		});
+
+		return { updated: result.length };
+	},
+});
+```
+
+- `target` — conflict column(s) to detect existing rows
+- `set` — columns to update on conflict (omit to keep existing values)
+- Supports single or array of values
+
 ### 3.3 Handler file placement
 
 Put handlers under `packages/backend/src` (including nested directories). Example patterns already used in this repo:
@@ -372,6 +469,13 @@ Inside handlers, you commonly use:
 
 - `ctx.db.<table>.findMany/findFirst/insert/update/upsert/delete`
 - aggregate helpers like `count` and `avg`
+- `count` supports `where`, `field`, `distinct`, and `with` for filtered relation counts
+- `avg` supports `where`, `field`, `distinct`, and `with` for filtered relation averages
+- `where` supports shorthand operators: `eq`, `ne`, `in`, `nin`, `gt`, `gte`, `lt`, `lte`, `exists`, `regex`, `$options`, `includes`, `includesAny`, `length`
+- `with` supports `_count` and `_avg` for relation-level aggregate results (returned as `XxxAggregate`)
+- `orderBy` accepts `{ column, direction }` or array thereof
+- `geoWithin` for geospatial distance queries (Haversine formula)
+- `upsert` supports `target` (conflict columns) and `set` (on-conflict update columns)
 - `ctx.error(status, message, details)` for typed failures
 
 See real examples in:

package/cli/schema-compiler.ts

@@ -821,6 +821,8 @@ function emitManyToManyRuntimeMetadata(definition: SchemaDefinition): string {
 				junctionTable: ${quote(relation.junctionTable)},
 				sourceField: ${quote(relation.sourceField ?? "")},
 				targetField: ${quote(relation.targetField ?? "")},
+				referenceField: ${quote(relation.referenceField ?? "id")},
+				targetReferenceField: ${quote(relation.targetReferenceField ?? "id")},
 			},`,
 			);
 		}

package/cli/templates/dashboard/builders/functions/tree-builder.ts

@@ -0,0 +1,47 @@
+import { DiscoveredHandlerOperation } from "../../../../utils/handler-discovery";
+
+export type TreeNode = {
+	name: string;
+	type: "folder";
+	children: TreeNode[];
+	handlers: DiscoveredHandlerOperation[];
+};
+
+export function buildFunctionTree(
+	handlers: DiscoveredHandlerOperation[],
+): TreeNode[] {
+	const root: TreeNode = {
+		name: "root",
+		type: "folder",
+		children: [],
+		handlers: [],
+	};
+
+	for (const handler of handlers) {
+		const segments = handler.clientSegments ?? [handler.exportName];
+		let current = root;
+
+		for (let i = 0; i < segments.length - 1; i++) {
+			const segment = segments[i];
+			let child = current.children.find(
+				(c) => c.name === segment && c.type === "folder",
+			);
+
+			if (!child) {
+				child = {
+					name: segment,
+					type: "folder",
+					children: [],
+					handlers: [],
+				};
+				current.children.push(child);
+			}
+
+			current = child;
+		}
+
+		current.handlers.push(handler);
+	}
+
+	return root.children;
+}

package/cli/templates/dashboard/builders/navigation.ts

@@ -1,6 +1,7 @@
 import { DiscoveredSchema } from "../../../utils/schema-discovery";
 import { DiscoveredHandlerOperation } from "../../../utils/handler-discovery";
 import { TableInfo } from "../types";
+import { buildFunctionTree, TreeNode } from "./functions/tree-builder";
 
 export function collectTablesInfo(schema: DiscoveredSchema): TableInfo[] {
 	return schema.tables.map((table) => ({
@@ -33,35 +34,67 @@ export function buildSidebarTableList(tablesInfo: TableInfo[]): string {
 \t\t\t\t\t${tableItems}`;
 }
 
+function renderTreeNode(node: TreeNode, depth: number): string {
+	const indent = "  ".repeat(depth);
+	const hasChildren = node.children.length > 0;
+	const hasHandlers = node.handlers.length > 0;
+	const isExpandable = hasChildren || hasHandlers;
+
+	let html = "";
+
+	if (isExpandable) {
+		const folderId = `folder-${node.name.replace(/[^a-zA-Z0-9]/g, "-")}-${depth}`;
+		html += `\n${indent}<li data-name="${node.name}" class="folder-item">`;
+		html += `\n${indent}  <details class="group/folder" open>`;
+		html += `\n${indent}    <summary class="sidebar-link flex items-center gap-2 px-3 py-2 text-sm rounded-lg w-full cursor-pointer list-none">`;
+		html += `\n${indent}      <iconify-icon icon="solar:folder-bold-duotone" width="16" height="16" class="opacity-50 shrink-0 transition-transform group-open/folder:rotate-0"></iconify-icon>`;
+		html += `\n${indent}      <span class="truncate font-medium">${node.name}</span>`;
+		html += `\n${indent}    </summary>`;
+		html += `\n${indent}    <ul class="flex flex-col gap-0.5 ml-4 border-l border-base-200 pl-2">`;
+
+		for (const child of node.children) {
+			html += renderTreeNode(child, depth + 2);
+		}
+
+		for (const handler of node.handlers) {
+			const icon = handler.kind === "query" ? "solar:reorder-linear" : "solar:bolt-linear";
+			html += `\n${indent}      <li data-name="${handler.exportName}">`;
+			html += `\n${indent}        <a href="/admin/functions${handler.routePath}" hx-get="/admin/functions${handler.routePath}" hx-target="#main-content" hx-push-url="true" hx-swap="outerHTML" class="sidebar-link flex items-center gap-2 px-3 py-2 text-sm rounded-lg w-full">`;
+			html += `\n${indent}          <iconify-icon icon="${icon}" width="16" height="16" class="opacity-50 shrink-0"></iconify-icon>`;
+			html += `\n${indent}          <span class="truncate">${handler.exportName}</span>`;
+			html += `\n${indent}        </a>`;
+			html += `\n${indent}      </li>`;
+		}
+
+		html += `\n${indent}    </ul>`;
+		html += `\n${indent}  </details>`;
+		html += `\n${indent}</li>`;
+	} else {
+		for (const handler of node.handlers) {
+			const icon = handler.kind === "query" ? "solar:reorder-linear" : "solar:bolt-linear";
+			html += `\n${indent}<li data-name="${handler.exportName}">`;
+			html += `\n${indent}  <a href="/admin/functions${handler.routePath}" hx-get="/admin/functions${handler.routePath}" hx-target="#main-content" hx-push-url="true" hx-swap="outerHTML" class="sidebar-link flex items-center gap-2 px-3 py-2 text-sm rounded-lg w-full">`;
+			html += `\n${indent}    <iconify-icon icon="${icon}" width="16" height="16" class="opacity-50 shrink-0"></iconify-icon>`;
+			html += `\n${indent}    <span class="truncate">${handler.exportName}</span>`;
+			html += `\n${indent}  </a>`;
+			html += `\n${indent}</li>`;
+		}
+	}
+
+	return html;
+}
+
 export function buildSidebarFunctionList(
 	handlers: DiscoveredHandlerOperation[],
 ): string {
 	const queries = handlers.filter((h) => h.kind === "query");
 	const mutations = handlers.filter((h) => h.kind === "mutation");
 
-	const queryItems = queries
-		.map(
-			(h) => `
-		<li data-name="${h.exportName}">
-			<a href="/admin/functions${h.routePath}" hx-get="/admin/functions${h.routePath}" hx-target="#main-content" hx-push-url="true" hx-swap="outerHTML" class="sidebar-link flex items-center gap-2 px-3 py-2 text-sm rounded-lg w-full">
-				<iconify-icon icon="solar:reorder-linear" width="16" height="16" class="opacity-50 shrink-0"></iconify-icon>
-				<span class="truncate">${h.exportName}</span>
-			</a>
-		</li>`,
-		)
-		.join("");
+	const queryTree = buildFunctionTree(queries);
+	const mutationTree = buildFunctionTree(mutations);
 
-	const mutationItems = mutations
-		.map(
-			(h) => `
-		<li data-name="${h.exportName}">
-			<a href="/admin/functions${h.routePath}" hx-get="/admin/functions${h.routePath}" hx-target="#main-content" hx-push-url="true" hx-swap="outerHTML" class="sidebar-link flex items-center gap-2 px-3 py-2 text-sm rounded-lg w-full">
-				<iconify-icon icon="solar:bolt-linear" width="16" height="16" class="opacity-50 shrink-0"></iconify-icon>
-				<span class="truncate">${h.exportName}</span>
-			</a>
-		</li>`,
-		)
-		.join("");
+	const queryItems = queryTree.map((node) => renderTreeNode(node, 0)).join("");
+	const mutationItems = mutationTree.map((node) => renderTreeNode(node, 0)).join("");
 
 	return `
 		<div id="pane-functions" class="flex flex-col h-full hidden">

package/cli/templates/dashboard/components/layout.ts

@@ -112,6 +112,23 @@ function Layout(props: { children: any; title: string; hideSidebar?: boolean })
 			}
 			.sidebar-link:hover iconify-icon { opacity: 0.7; }
 
+			.folder-item { list-style: none; }
+			.folder-item > details > summary { list-style: none; }
+			.folder-item > details > summary::-webkit-details-marker { display: none; }
+			.folder-item > details > summary::before {
+				content: '';
+				display: inline-block;
+				width: 16px;
+				height: 16px;
+				background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='currentColor'%3E%3Cpath d='M8.59 16.59L13.17 12 8.59 7.41 10 6l6 6-6 6z'/%3E%3C/svg%3E");
+				background-size: contain;
+				transition: transform 0.15s ease;
+				opacity: 0.45;
+			}
+			.folder-item > details[open] > summary::before {
+				transform: rotate(90deg);
+			}
+
 			.table th {
 				font-weight: 500;
 				font-size: 0.78rem;
@@ -291,9 +308,24 @@ function Layout(props: { children: any; title: string; hideSidebar?: boolean })
 
 			function filterFunctions(query) {
 				var q = query.toLowerCase();
+				document.querySelectorAll('#pane-functions details').forEach(function(details) {
+					details.open = true;
+				});
 				document.querySelectorAll('#pane-functions li').forEach(function(li) {
 					var name = (li.getAttribute('data-name') || li.textContent).toLowerCase();
-					li.style.display = name.includes(q) ? '' : 'none';
+					var matches = name.includes(q);
+					li.style.display = matches ? '' : 'none';
+					if (!matches && li.classList.contains('folder-item')) {
+						var childItems = li.querySelectorAll('li');
+						childItems.forEach(function(child) {
+							var childName = (child.getAttribute('data-name') || child.textContent).toLowerCase();
+							if (childName.includes(q)) {
+								li.style.display = '';
+								var parentDetails = li.closest('details');
+								if (parentDetails) parentDetails.open = true;
+							}
+						});
+					}
 				});
 			}
 

package/cli/templates/handlers/generators/types/query-definitions/filter-and-where-types.ts

@@ -46,7 +46,7 @@ type FieldOperators<T, TFieldKey extends string = string> = {
 	lte?: Comparable<T>;
 	exists?: boolean;
 	regex?: RegexOperand<T>;
-	options?: string;
+	$options?: string;
 	geoWithin?: GeoWithinOperandForField<TFieldKey>;
 	includes?: T extends ReadonlyArray<infer E> ? ReadonlyArray<E> : never;
 	includesAny?: T extends ReadonlyArray<infer E> ? ReadonlyArray<E> : never;
@@ -258,11 +258,31 @@ export type QueryInsertArgs<TName extends TableName> = {
 };
 
 export type QueryUpdateArgs<TName extends TableName> = {
-	set: Partial<TableInsertModel<TName>>;
+	set: Partial<TableInsertModel<TName>> & ManyToManyUpdateSetFields<TName>;
 	where?: WhereInput<TableModel<TName>, TName>;
 	limit?: number;
 };
 
+type ManyToManyUpdateSetFields<TName extends TableName> = {
+	[TRelationName in RuntimeRelationName<TName>]?: RuntimeRelationKind<TName, TRelationName> extends "manyToMany"
+		? ManyToManyUpdateInput<TName, TRelationName>
+		: never;
+};
+
+type ManyToManyUpdateInput<
+	TSourceTable extends TableName,
+	TRelationName extends RuntimeRelationName<TSourceTable>,
+> = {
+	items: Array<ManyToManyUpdateItem<TargetTableForRelation<TSourceTable, TRelationName>>>;
+	mode?: "merge" | "overwrite";
+};
+
+type ManyToManyUpdateItem<TTargetTable extends TableName> =
+	| ("id" extends keyof TableModel<TTargetTable>
+			? TableModel<TTargetTable>["id"]
+			: never)
+	| Partial<TableInsertModel<TTargetTable>>;
+
 export type QueryDeleteArgs<TName extends TableName> = {
 	where?: WhereInput<TableModel<TName>, TName>;
 	limit?: number;