create-questpie 2.0.2 → 2.0.4

package/skills/questpie/references/crud-api.md

@@ -1,6 +1,6 @@
 ---
 name: questpie-core/crud-api
-description: QUESTPIE CRUD API find findOne create update delete count updateMany deleteMany query operators where filter sort orderBy pagination limit offset with select relations depth context accessMode collections globals client server typesafe
+description: QUESTPIE CRUD API find findOne create updateById updateMany updateBatch deleteById deleteMany restoreById count atomic conditional update claim optimistic locking query operators where filter sort orderBy pagination limit offset with select relations depth context accessMode collections globals client server typesafe
   - questpie-core
 ---
 
@@ -16,8 +16,7 @@ Inside any handler, `collections` and `globals` are injected via context. The cu
 
 ```ts
 // routes/get-published.ts
-import { route } from "questpie";
-
+import { route } from "questpie/services";
 export default route()
 	.get()
 	.handler(async ({ collections }) => {
@@ -47,6 +46,23 @@ const result = await app.collections.posts.find(
 
 ## Collection Operations
 
+One vocabulary on both surfaces (server CRUD and client SDK):
+
+| Concept | Method | Returns |
+| --- | --- | --- |
+| list (paginated) | `find(options)` | `{ docs: T[], totalDocs: number }` |
+| single by query | `findOne(options)` | `T \| null` |
+| count | `count(options)` | `number` |
+| create | `create(data)` | `T` |
+| update by id | `updateById({ id, data })` | `T` (throws notFound) |
+| bulk update by where | `updateMany({ where, data })` | `T[]` (winners) |
+| per-record batch | `updateBatch({ updates })` | `T[]` |
+| delete by id | `deleteById({ id })` | `{ success }` (throws notFound) |
+| bulk delete by where | `deleteMany({ where })` | `{ success, count }` |
+| restore by id | `restoreById({ id })` | `T` (softDelete only) |
+
+Deprecated aliases (removed in v4): server `update`/`delete` = bulk (`updateMany`/`deleteMany`); client `update`/`delete`/`restore` = by-id (`updateById`/`deleteById`/`restoreById`). Avoid them — the same names mean different things on each surface. Accessing a method that does not exist on server CRUD throws a `TypeError` listing valid methods (it does NOT return `undefined`).
+
 ### `find(options)`
 
 List documents with filtering, sorting, and pagination.
@@ -91,58 +107,111 @@ const post = await collections.posts.create({
 // post: T (created record with id)
 ```
 
-### `update(options)`
+### `updateById(options)`
 
-Update a document matching `where`. Pass changed fields in `data`.
+Update a single document by id. Returns the updated record; throws `notFound` if the record does not exist (or vanished concurrently).
 
 ```ts
-const updated = await collections.posts.update({
-	where: { id: "abc-123" },
+const updated = await collections.posts.updateById({
+	id: "abc-123",
 	data: { status: "published" },
 });
 // updated: T (updated record)
 ```
 
-### `delete(options)`
+### `updateMany(options)`
 
-Delete documents matching `where`.
+Bulk update all documents matching `where`. Returns an **array** of the updated records — never a single object.
 
 ```ts
-await collections.posts.delete({
-	where: { id: "abc-123" },
+const updated = await collections.posts.updateMany({
+	where: { status: "draft" },
+	data: { status: "archived" },
 });
+// updated: T[] — exactly the rows that were written
 ```
 
-### `count(options)`
+`updateMany` is claim-checked: inside the write transaction the matched rows are locked and `where` is re-evaluated, so rows changed by a concurrent writer are skipped instead of silently overwritten. The returned array reports exactly the winners.
 
-Count documents matching a filter.
+#### Atomic conditional updates (claims, optimistic locking)
+
+Use a conditional `where` + the array length as the win/lose signal:
 
 ```ts
-const total = await collections.posts.count({
-	where: { status: "published" },
-});
-// total: number
+// Claim: of two parallel claims, EXACTLY ONE wins
+const claimed = await collections.event_members.updateMany(
+	{
+		where: { id: memberId, user: { isNull: true } },
+		data: { user: newUserId },
+	},
+	{ accessMode: "system" },
+);
+if (claimed.length === 0) {
+	// Lost the race (or row vanished) — handle explicitly
+}
+
+// Optimistic concurrency: write only if the revision is unchanged
+const bumped = await collections.documents.updateMany(
+	{ where: { id, revision: doc.revision }, data: { body, revision: doc.revision + 1 } },
+	ctx,
+);
+if (bumped.length === 0) throw new Error("Conflict — reload and retry");
 ```
 
-### `updateMany(options)`
+Hook timing: `beforeValidate`/`beforeChange` run before the transaction on candidates (intent — may fire for losers); `afterChange`, versioning, and the return value are winners-only (fact).
 
-Bulk update all documents matching `where`.
+### `updateBatch(options)`
+
+Distinct data per record, one transaction.
 
 ```ts
-await collections.posts.updateMany({
-	where: { status: "draft" },
-	data: { status: "archived" },
+const updated = await collections.posts.updateBatch({
+	updates: [
+		{ id: "a", data: { order: 1 } },
+		{ id: "b", data: { order: 2 } },
+	],
 });
+// updated: T[]
+```
+
+### `deleteById(options)`
+
+Delete a single document by id (soft delete when enabled). Throws `notFound` if missing.
+
+```ts
+await collections.posts.deleteById({ id: "abc-123" });
+// { success: true }
 ```
 
 ### `deleteMany(options)`
 
-Bulk delete all documents matching `where`.
+Bulk delete all documents matching `where`. Claim-checked like `updateMany` — `count` is the number of rows that still matched at delete time.
 
 ```ts
-await collections.posts.deleteMany({
+const result = await collections.posts.deleteMany({
 	where: { status: "archived" },
 });
+// result: { success: true, count: number }
+```
+
+### `restoreById(options)`
+
+Restore a soft-deleted document (collections with `softDelete: true`).
+
+```ts
+const restored = await collections.posts.restoreById({ id: "abc-123" });
+// restored: T
+```
+
+### `count(options)`
+
+Count documents matching a filter.
+
+```ts
+const total = await collections.posts.count({
+	where: { status: "published" },
+});
+// total: number
 ```
 
 ## Global Operations
@@ -204,6 +273,20 @@ const result = await collections.posts.find({
 });
 ```
 
+Multi-field sorting: order determines priority (first = primary sort). All
+three syntaxes work, including inside relation `with` options:
+
+```ts
+// Array syntax (preferred for explicit priority)
+orderBy: [{ status: "desc" }, { createdAt: "desc" }]
+
+// Object syntax (key order = priority)
+orderBy: { status: "desc", createdAt: "desc" }
+
+// Function syntax
+orderBy: (table, { asc, desc }) => [desc(table.status), asc(table.title)]
+```
+
 ## Pagination
 
 Use `limit` and `offset`:
@@ -216,6 +299,38 @@ const page2 = await collections.posts.find({
 // page2.totalDocs = total count across all pages
 ```
 
+### Keyset (cursor) pagination
+
+For stable pagination over changing data, use a tuple cursor of
+`(createdAt, id)` with a matching multi-field `orderBy`. System timestamps
+are stored with millisecond precision (`timestamp(3)`), so a `Date` you read
+back equals the stored value exactly — cursor comparisons are exact:
+
+```ts
+const page = await collections.posts.find({
+	where: cursor
+		? {
+				OR: [
+					{ createdAt: { lt: cursor.createdAt } },
+					{
+						AND: [
+							{ createdAt: { eq: cursor.createdAt } },
+							{ id: { lt: cursor.id } },
+						],
+					},
+				],
+			}
+		: undefined,
+	orderBy: [{ createdAt: "desc" }, { id: "desc" }],
+	limit: 20,
+});
+const last = page.docs.at(-1);
+const nextCursor = last ? { createdAt: last.createdAt, id: last.id } : null;
+```
+
+Always use the explicit `{ eq: ... }` operator for `Date` cursor values —
+do not pass a bare `Date` as an equality shorthand.
+
 ## Relations
 
 Relations are NOT populated by default. Use `with` to eager-load:
@@ -252,9 +367,46 @@ export default route()
 	});
 ```
 
+### Partial Overrides (Inside Request Scope)
+
+The optional second argument of every CRUD call merges with the ambient request scope. Priority: **explicit param → ALS scope (`runWithContext`) → defaults** (`accessMode: "system"`, `locale: "en"`). A bare `{ accessMode: "system" }` elevates only the mode — the request's `session`, `db`, and `locale` ride along automatically. The inverse holds too:
+
+```ts
+// Inside any handler / hook / Better Auth callback:
+await collections.posts.updateMany(
+	{ where: { author: oldId }, data: { author: newId } },
+	{ accessMode: "system" }, // mode elevated; session/db/locale inherited
+);
+
+await collections.posts.find({}, { accessMode: "user" }); // rules re-enabled against inherited session
+```
+
+Never re-thread `session`/`locale` by hand when you only want a different access mode.
+
+### Transactions
+
+`withTransaction(db, fn)` (from `questpie`) runs multiple CRUD calls atomically — calls inside the callback inherit the transaction connection through the ALS scope, and nested `withTransaction` calls reuse the open transaction. Queue side effects for after COMMIT with `onAfterCommit`:
+
+```ts
+import { onAfterCommit, withTransaction } from "questpie";
+
+await withTransaction(db, async () => {
+	const order = await collections.orders.create({ ... });
+	await collections.inventory.updateMany({
+		where: { sku: order.sku, status: "available" },
+		data: { status: "reserved" },
+	});
+	onAfterCommit(async () => {
+		await queue.notifyWarehouse.publish({ orderId: order.id });
+	});
+});
+```
+
+Do not run output-hook-heavy reads (blocks/upload `afterRead`) inside an open transaction unless necessary — they inherit the tx connection too.
+
 ### In Scripts / Seeds
 
-Create an explicit context with `app.createContext()`:
+Outside any request scope, create an explicit context with `app.createContext()`:
 
 ```ts
 // System mode -- bypasses all access control
@@ -266,22 +418,44 @@ const ctx = await app.createContext({ accessMode: "user" });
 
 ## Client API
 
-The client SDK mirrors server operations:
+The client SDK uses the same vocabulary:
 
 ```ts
 const posts = await client.collections.posts.find({ limit: 10 });
 const post = await client.collections.posts.findOne({ where: { id: "abc" } });
 const created = await client.collections.posts.create({ title: "New" });
-const updated = await client.collections.posts.update({
+const updated = await client.collections.posts.updateById({
 	id: "abc",
 	data: { title: "Updated" },
 });
-await client.collections.posts.delete({ id: "abc" });
+await client.collections.posts.deleteById({ id: "abc" });
+const many = await client.collections.posts.updateMany({
+	where: { status: "draft" },
+	data: { status: "review" },
+});
+await client.collections.posts.deleteMany({ where: { status: "archived" } });
 const count = await client.collections.posts.count({
 	where: { status: "draft" },
 });
 ```
 
+### Live Queries (Client Only)
+
+Every read has a live form — `live()` mirrors `find()` (same options, same snapshot type) and pushes access-controlled snapshots over SSE. Globals mirror `get()`: `client.globals.<name>.live(...)`. See AGENTS.md §19 Realtime:
+
+```ts
+const stop = client.collections.posts.live(
+	{ where: { status: "published" }, with: { author: true } },
+	(snap) => render(snap.docs), // typed find() result
+);
+stop(); // unsubscribe
+
+// AsyncGenerator form (workers, agents, tests)
+for await (const snap of client.collections.posts.liveIter({ limit: 10 })) {
+	render(snap.docs);
+}
+```
+
 ### Upload (Client Only)
 
 For upload collections:
@@ -363,6 +537,34 @@ export default route()
 	});
 ```
 
+### HIGH: Expecting updateMany() to return a single record
+
+Server bulk update returns an **array** of updated records:
+
+```ts
+// WRONG -- updateMany returns T[], not T
+const updated = await collections.posts.updateMany({
+	where: { id: "abc" },
+	data: { status: "published" },
+});
+console.log(updated.status); // undefined!
+
+// CORRECT
+const [updated] = await collections.posts.updateMany({
+	where: { id: "abc" },
+	data: { status: "published" },
+});
+// or, for a single record by id:
+const updated2 = await collections.posts.updateById({
+	id: "abc",
+	data: { status: "published" },
+});
+```
+
+### HIGH: `update`/`delete` mean different things on server vs client
+
+On server CRUD, `update`/`delete` are deprecated aliases of the BULK operations (`{ where, data }` → `T[]`). On the client SDK they are by-id operations (`{ id, data }` → `T`). Always use the unambiguous names: `updateById`/`deleteById`/`restoreById` for single records, `updateMany`/`deleteMany` for bulk. Calling a method that does not exist (e.g. a typo) on server CRUD throws a `TypeError` listing the valid methods.
+
 ### MEDIUM: Wrong create() signature
 
 `create()` takes a flat data object, NOT `{ data: {...} }`:
@@ -375,4 +577,4 @@ await collections.posts.create({ data: { title: "Hello" } });
 await collections.posts.create({ title: "Hello", body: "World" });
 ```
 
-Note: `update()` DOES use `{ where, data }` -- only `create()` is flat.
+Note: `updateById()`/`updateMany()` DO use `{ id/where, data }` -- only `create()` is flat.

package/skills/questpie/references/data-modeling.md

@@ -62,6 +62,24 @@ export default collection("posts")
 | `.options({...})`                               | Timestamps, versioning, soft delete     |
 | `.search({...})`                                | Search indexing                         |
 | `.searchable(string[])`                         | Searchable fields                       |
+| `.merge(other)`                                 | Extend a same-name builder (see below)  |
+
+### Extending Collections — `.merge()`
+
+To extend a collection a module already provides, merge its builder — never redefine the collection from scratch (same-key registration replaces the module's collection wholesale):
+
+```ts
+import { starterModule } from "questpie/app";
+import { collection } from "#questpie/factories";
+
+export default collection("user")
+	.merge(starterModule.collections.user)
+	.fields(({ f }) => ({
+		internalNotes: f.textarea(),
+	}));
+```
+
+Fields/options/extension keys combine by key (merged-in side wins), hooks concatenate, and `.fields()` after `.merge()` is cumulative — it never wipes merged fields. The result stays fully typed.
 
 ### Collection Options
 
@@ -94,6 +112,10 @@ import { uniqueIndex } from "drizzle-orm/pg-core";
 })
 ```
 
+Live Preview uses the existing admin `FormView`, Preview button, `LivePreviewMode`, and iframe. Do not introduce a separate visual-edit form API, a second default form view, or parallel preview API names.
+
+When workflow is the publication source for pages, public reads use `stage: "published"` and preview/draft-mode reads can load the working stage for authorized editors. Do not add duplicate publication booleans for the same concern.
+
 ### Access Control
 
 ```ts
@@ -238,8 +260,7 @@ Every field accepts:
 ### Virtual (Computed) Fields
 
 ```ts
-import { sql } from "questpie";
-
+import { sql } from "questpie/builders";
 displayTitle: f.text().virtual(sql<string>`(
     SELECT COALESCE(name, 'Unknown') || ' - ' ||
     TO_CHAR("scheduledAt", 'YYYY-MM-DD HH24:MI')
@@ -256,7 +277,7 @@ All relations are defined via `f.relation()` inside `.fields()`.
 ### Belongs-To (Single)
 
 ```ts
-author: f.relation("users").required(),
+author: f.relation("user").required(),
 barber: f.relation("barbers").required().onDelete("cascade"),
 ```
 
@@ -315,8 +336,7 @@ const appointments = await collections.appointments.find({
 ### Locale Configuration
 
 ```ts title="config/app.ts"
-import { appConfig } from "questpie";
-
+import { appConfig } from "questpie/app";
 export default appConfig({
 	locale: {
 		locales: [
@@ -446,7 +466,7 @@ collection("posts").relations({ author: belongsTo("users") });
 
 // CORRECT -- use f.relation() inside .fields()
 collection("posts").fields(({ f }) => ({
-	author: f.relation("users"),
+	author: f.relation("user"),
 }));
 ```
 

package/skills/questpie/references/extend.md

@@ -15,7 +15,7 @@ A plugin tells codegen what to discover and what types to generate. Plugins cont
 ### Plugin Structure
 
 ```ts
-import type { CodegenPlugin } from "questpie";
+import type { CodegenPlugin } from "questpie/codegen";
 
 export function myPlugin(): CodegenPlugin {
 	return {
@@ -76,7 +76,7 @@ export function myPlugin(): CodegenPlugin {
 ### Register in Config
 
 ```ts title="questpie.config.ts"
-import { runtimeConfig } from "questpie";
+import { runtimeConfig } from "questpie/app";
 import { myPlugin } from "my-plugin-package";
 
 export default runtimeConfig({
@@ -86,6 +86,70 @@ export default runtimeConfig({
 });
 ```
 
+Use direct `runtimeConfig({ plugins })` registration only for standalone codegen plugins or custom setups that do not ship a module. Reusable packages should usually attach the plugin to a static module and let codegen extract it from `modules.ts`.
+
+### Configurable Codegen-Aware Modules
+
+When a package ships a module and a `CodegenPlugin`, keep module identity static and put runtime options in a plugin-discovered config file. Codegen imports `modules.ts` before runtime app creation, so it must be able to see the same module/plugin tree regardless of environment or runtime options.
+
+#### DO THIS
+
+```ts title="modules.ts"
+import { observabilityModule } from "@questpie/observability/server";
+
+export default [observabilityModule] as const;
+```
+
+```ts title="config/observability.ts"
+import { observabilityConfig } from "@questpie/observability/server";
+
+export default observabilityConfig({
+	serviceName: "barbershop",
+	enabled: process.env.NODE_ENV === "production",
+	otlpEndpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
+});
+```
+
+```ts title="@questpie/observability/server.ts"
+export const observabilityModule = module({
+	name: "questpie-observability",
+	plugin: observabilityPlugin(),
+	services: {
+		observability: service({
+			namespace: null,
+			lifecycle: "singleton",
+			create: ({ app, logger }) =>
+				createObservabilityService(app.state.config?.observability, logger),
+		}),
+	},
+});
+```
+
+The plugin contributes `config/observability.ts` as a discover pattern and a typed singleton factory such as `observabilityConfig()`. The service reads the resolved config at runtime from `app.state.config.observability`.
+
+#### DON'T DO THIS
+
+Do not make runtime options the main API for modules that contribute codegen plugins:
+
+```ts title="modules.ts"
+export default [
+	observabilityModule({
+		serviceName: "barbershop",
+		enabled: process.env.NODE_ENV === "production",
+	}),
+] as const;
+```
+
+Do not conditionally include codegen-aware modules or plugins:
+
+```ts title="modules.ts"
+export default [
+	process.env.OTEL_ENABLED ? observabilityModule : undefined,
+].filter(Boolean);
+```
+
+Factory modules are acceptable only for simple runtime-only modules whose plugin identity and generated contributions do not change. If the package contributes discover patterns, generated factories, module categories, views, components, fields, or collection/global extensions, use **static module + `config/*.ts` singleton factory**.
+
 ### Plugin Lifecycle
 
 1. **Discovery** -- codegen scans for files matching category patterns and discover patterns
@@ -103,7 +167,9 @@ The admin module contributes a codegen plugin to both `"server"` and `"admin-cli
 A module is a reusable package that contributes entities to any QUESTPIE project.
 
 ```ts
-import { module, collection, job } from "questpie";
+import { module } from "questpie/app";
+import { collection } from "questpie/builders";
+import { job } from "questpie/services";
 import { z } from "zod";
 
 const notificationsCollection = collection("notifications")
@@ -171,10 +237,35 @@ export const notificationsModule = module({
 | `seeds`       | `Seed[]`      | Seed data                |
 | `messages`    | `Record`      | i18n translations        |
 
+### How Module Contributions Merge
+
+When several modules (and the app) contribute the same key, `createApp()` merges them deterministically — later modules win per entry:
+
+| Key | Strategy |
+| --- | --- |
+| `collections`, `globals`, `jobs`, `routes`, `fields`, `services` | record spread-merge — same key: later wins |
+| `messages` | deep-merge by locale — same message key: later wins |
+| `migrations`, `seeds` | array concatenation |
+| `config.*` (app, auth, admin, plugin config keys) | per-key strategies; `auth`/`admin` deep-merge; unknown keys: incoming replaces existing |
+| anything else | auto-detect: object+object → spread, array+array → concat, otherwise incoming wins |
+
+The merge helpers behind these strategies are exported from `questpie/app` for module authors combining config fragments of their own:
+
+```ts
+import { lastWins, mergeConcat, mergeDeepConcat, mergeRecord, type MergeFn } from "questpie/app";
+
+mergeRecord(a, b); // { ...a, ...b }
+mergeConcat(a, b); // [...a, ...b]
+mergeDeepConcat(a, b); // spread objects, concat array-valued props
+lastWins(a, b); // b
+```
+
+Use them (instead of hand-rolled spreads) when a module exposes its own "combine these contributions" surface — the semantics then match what the framework does for built-in keys.
+
 ### Using a Module
 
 ```ts title="modules.ts"
-import { adminModule } from "@questpie/admin/server";
+import { adminModule } from "@questpie/admin/modules/admin";
 import { notificationsModule } from "my-notifications-package";
 
 export default [adminModule, notificationsModule] as const;
@@ -217,7 +308,7 @@ A custom field defines:
 The `Field` class is an immutable builder:
 
 ```ts
-import { Field } from "questpie";
+import { Field } from "questpie/builders";
 
 // Each method returns a new Field with updated type state
 f.text(255).required().label({ en: "Name" }).admin({ placeholder: "..." });
@@ -248,7 +339,7 @@ QUESTPIE ships with adapters for Hono, Elysia, and Next.js. For other frameworks
 ### Generic Fetch Handler
 
 ```ts
-import { createFetchHandler } from "questpie";
+import { createFetchHandler } from "questpie/http";
 import { app } from "#questpie";
 
 const handler = createFetchHandler(app, { basePath: "/api" });
@@ -296,7 +387,7 @@ export const { GET, POST, PATCH, DELETE } = questpieNextRouteHandlers(app, {
 
 ```ts title="src/routes/api/$.ts"
 import { createAPIFileRoute } from "@tanstack/react-start/api";
-import { createFetchHandler } from "questpie";
+import { createFetchHandler } from "questpie/http";
 import { app } from "#questpie";
 
 const handler = createFetchHandler(app, { basePath: "/api" });

package/skills/questpie/references/field-types.md

@@ -14,6 +14,9 @@ Complete configuration patterns for built-in QUESTPIE field types. Fields use fl
 | `.inputOptional()`   | Optional in API input but required in DB    |
 | `.admin(config)`     | Admin UI rendering hints                    |
 | `.virtual(sql)`      | SQL expression for computed read-only field |
+| `.zod(fn)`           | Extend/replace Zod schema (output narrows value type) |
+| `.drizzle(fn)`       | Raw Drizzle column builder — constraints/SQL defaults land in DDL; `$type` narrows value type |
+| `.$type<T>()`        | Explicitly set TS value type (type-level; mainly json) |
 
 ## `f.text(options?)`
 
@@ -206,7 +209,7 @@ Reference to another collection.
 Belongs-to (single):
 
 ```ts
-author: f.relation("users").required(),
+author: f.relation("user").required(),
 category: f.relation("categories").onDelete("set null"),
 ```
 
@@ -355,13 +358,22 @@ pageContent: f.blocks(),
 
 ## `f.json(options?)`
 
-Raw JSON data. No schema validation.
+Raw JSON data. No schema validation by default; value types as loose `JsonValue`.
 
 ```ts
 metadata: f.json(),
 rawConfig: f.json().label("Configuration"),
 ```
 
+Type it explicitly with `.$type<T>()` (type only) or `.zod()` (type + runtime validation) — the type flows into CRUD select/insert types:
+
+```ts
+type Layout = { rows: { id: string; span: number }[] };
+
+layout: f.json().$type<Layout>(),
+settings: f.json().zod(() => z.object({ theme: z.enum(["light", "dark"]) })),
+```
+
 ## Admin Meta Options
 
 The `meta.admin` object controls field rendering in the admin panel: