appflare 0.2.41 → 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/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;

package/cli/templates/handlers/generators/types/query-runtime/runtime-write.ts

@@ -561,6 +561,8 @@ export function generateQueryRuntimeWriteSection(): string {
 					return rows;
 				},
 				update: async (args: QueryUpdateArgs<TableName>) => {
+					const transaction = ($db as any).transaction;
+
 					const whereFilter = buildWhereFilter(
 						table,
 						args.where as Record<string, unknown> | undefined,
@@ -569,27 +571,286 @@ export function generateQueryRuntimeWriteSection(): string {
 
 					const setPayload = args.set as Record<string, unknown>;
 					const cleanSetPayload: Record<string, unknown> = {};
+					const relationPayloads: Array<{
+						relationName: string;
+						relation: RuntimeRelation;
+						value: unknown;
+					}> = [];
+
 					for (const [key, value] of Object.entries(setPayload)) {
-						if (value !== undefined) {
-							cleanSetPayload[key] = value;
+						if (value === undefined) continue;
+						const runtimeRelation = getRuntimeRelation(tableName, key);
+						if (runtimeRelation && runtimeRelation.kind === "manyToMany") {
+							relationPayloads.push({
+								relationName: key,
+								relation: runtimeRelation,
+								value,
+							});
+							continue;
 						}
+						cleanSetPayload[key] = value;
 					}
 
-					let updateQuery: any = ($db as any)
-						.update(table as any)
-						.set(cleanSetPayload as any);
+					const normalizeRelationValue = (
+						value: unknown,
+					): { items: unknown[]; mode: "merge" | "overwrite" } => {
+						if (Array.isArray(value)) {
+							return { items: value, mode: "merge" };
+						}
+						if (value && typeof value === "object") {
+							const record = value as Record<string, unknown>;
+							const items = Array.isArray(record.items) ? record.items : [];
+							const mode = record.mode === "overwrite" ? "overwrite" : "merge";
+							return { items, mode };
+						}
+						return { items: [], mode: "merge" };
+					};
+
+					const executeUpdateWithRelations = async (
+						tx: any,
+					): Promise<Array<TableModel<TableName>>> => {
+						let updateQuery: any = tx
+							.update(table as any)
+							.set(cleanSetPayload as any);
 
-					if (whereFilter) {
-						updateQuery = updateQuery.where(whereFilter);
-					}
-					if (typeof args.limit === "number" && typeof updateQuery.limit === "function") {
-						updateQuery = updateQuery.limit(args.limit);
-					}
-					if (typeof updateQuery.returning === "function") {
-						updateQuery = updateQuery.returning();
+						if (whereFilter) {
+							updateQuery = updateQuery.where(whereFilter);
+						}
+						if (
+							typeof args.limit === "number" &&
+							typeof updateQuery.limit === "function"
+						) {
+							updateQuery = updateQuery.limit(args.limit);
+						}
+						if (typeof updateQuery.returning === "function") {
+							updateQuery = updateQuery.returning();
+						}
+
+						const rows = (await updateQuery) as Array<TableModel<TableName>>;
+						if (rows.length === 0) return rows;
+
+						for (const row of rows) {
+							const parentId = (row as Record<string, unknown>)["id"];
+							if (parentId === undefined || parentId === null) continue;
+
+							for (const { relationName, relation, value } of relationPayloads) {
+								const { items, mode } = normalizeRelationValue(value);
+
+								const junctionTable = (mergedSchema as Record<string, unknown>)[
+									relation.junctionTable
+								];
+								if (!junctionTable) {
+									throw new Error(
+										"Unknown junction table '" +
+											relation.junctionTable +
+											"' for relation '" +
+											tableName +
+											"." +
+											relationName +
+											"'.",
+									);
+								}
+
+								const sourceField = relation.sourceField;
+								const targetField = relation.targetField;
+								if (!sourceField || !targetField) {
+									throw new Error(
+										"Relation '" +
+											tableName +
+											"." +
+											relationName +
+											"' is missing junction metadata fields.",
+									);
+								}
+
+								const parentReferenceField = relation.referenceField ?? "id";
+								const parentReferenceColumn = (table as Record<string, unknown>)[parentReferenceField];
+								if (!parentReferenceColumn) {
+									throw new Error(
+										"Table '" +
+											tableName +
+											"' is missing column '" +
+											parentReferenceField +
+											"' for relation '" +
+											relationName +
+											"'.",
+									);
+								}
+
+								const junctionSourceColumn = (junctionTable as Record<string, unknown>)[sourceField];
+								if (!junctionSourceColumn) {
+									throw new Error(
+										"Junction table '" +
+											relation.junctionTable +
+											"' is missing column '" +
+											sourceField +
+											"' for relation '" +
+											relationName +
+											"'.",
+									);
+								}
+
+								if (mode === "overwrite") {
+									await tx
+										.delete(junctionTable as any)
+										.where(eq(junctionSourceColumn as any, (row as Record<string, unknown>)[parentReferenceField] as any));
+								}
+
+								const referenceField = relation.targetReferenceField ?? "id";
+								const targetTable = (mergedSchema as Record<string, unknown>)[
+									relation.targetTable
+								];
+
+								const junctionTargetColumn =
+									(junctionTable as Record<string, unknown>)[targetField];
+								if (!junctionTargetColumn) {
+									throw new Error(
+										"Junction table '" +
+											relation.junctionTable +
+											"' is missing column '" +
+											targetField +
+											"'.",
+									);
+								}
+
+								for (const item of items) {
+									let targetId: unknown;
+
+									if (
+										typeof item === "string" ||
+										typeof item === "number" ||
+										typeof item === "bigint"
+									) {
+										targetId = item;
+									} else if (item && typeof item === "object") {
+										const record = item as Record<string, unknown>;
+										const existingId = record[referenceField];
+										if (existingId !== undefined && existingId !== null) {
+											targetId = existingId;
+										} else {
+											if (!targetTable) {
+												throw new Error(
+													"Unknown target table '" +
+														relation.targetTable +
+														"' for relation '" +
+														tableName +
+														"." +
+														relationName +
+														"'.",
+												);
+											}
+											let createQuery: any = tx
+												.insert(targetTable as any)
+												.values(record as any);
+											if (typeof createQuery.returning === "function") {
+												createQuery = createQuery.returning();
+											}
+											const createdRows =
+												(await createQuery) as Array<Record<string, unknown>>;
+											const created = createdRows[0];
+											if (!created) {
+												throw new Error(
+													"Failed to create relation target for '" +
+														tableName +
+														"." +
+														relationName +
+														"'.",
+												);
+											}
+											targetId = created[referenceField];
+											if (targetId === undefined || targetId === null) {
+												throw new Error(
+													"Created relation target for '" +
+														tableName +
+														"." +
+														relationName +
+														"' is missing '" +
+														referenceField +
+														"'.",
+												);
+											}
+										}
+									} else {
+										throw new Error(
+											"Relation '" +
+												tableName +
+												"." +
+												relationName +
+												"' expects an id or object payload.",
+										);
+									}
+
+									if (mode === "merge") {
+										const parentRefValue = (row as Record<string, unknown>)[parentReferenceField];
+										const existingLinks = await tx
+											.select()
+											.from(junctionTable as any)
+											.where(
+												and(
+													eq(junctionSourceColumn as any, parentRefValue as any),
+													eq(junctionTargetColumn as any, targetId as any),
+												),
+											);
+										if (existingLinks.length > 0) continue;
+									}
+
+									const parentRefValue = (row as Record<string, unknown>)[parentReferenceField];
+									await tx.insert(junctionTable as any).values({
+										[sourceField]: parentRefValue,
+										[targetField]: targetId,
+									} as any);
+								}
+							}
+						}
+
+						return rows;
+					};
+
+					let rows: Array<TableModel<TableName>>;
+					if (relationPayloads.length > 0) {
+						if (typeof transaction === "function") {
+							try {
+								rows = await transaction.call($db, (tx: any) =>
+									executeUpdateWithRelations(tx),
+								);
+							} catch (error) {
+								const message =
+									error instanceof Error ? error.message : String(error);
+								const lowered = message.toLowerCase();
+								if (
+									lowered.includes("failed query: begin") ||
+									lowered.includes('near "begin"') ||
+									lowered.includes("cannot start a transaction")
+								) {
+									rows = await executeUpdateWithRelations($db as any);
+								} else {
+									throw error;
+								}
+							}
+						} else {
+							rows = await executeUpdateWithRelations($db as any);
+						}
+					} else {
+						let updateQuery: any = ($db as any)
+							.update(table as any)
+							.set(cleanSetPayload as any);
+
+						if (whereFilter) {
+							updateQuery = updateQuery.where(whereFilter);
+						}
+						if (
+							typeof args.limit === "number" &&
+							typeof updateQuery.limit === "function"
+						) {
+							updateQuery = updateQuery.limit(args.limit);
+						}
+						if (typeof updateQuery.returning === "function") {
+							updateQuery = updateQuery.returning();
+						}
+
+						rows = (await updateQuery) as Array<TableModel<TableName>>;
 					}
 
-					const rows = (await updateQuery) as Array<TableModel<TableName>>;
 					emitMutation(
 						"update",
 						{