create-questpie 2.0.4 → 2.1.0

package/skills/questpie/references/type-inference.md

@@ -1,167 +0,0 @@
-# Type Inference Reference
-
-The schema is the single source of types. If you are hand-writing a type that restates a schema (a row shape, a session shape, a payload), stop — there is a sanctioned inference one-liner for it. Hand-rolled structural types drift silently (real schema `string | null` vs hand-rolled `string | undefined`) and structural mirrors of the CRUD generics produce deep error walls at every call site.
-
-## The Map — "I Need Type X"
-
-| # | You need | Write exactly this | Notes |
-| --- | --- | --- | --- |
-| 1 | Row of **another** collection | `import type { CollectionDoc } from "#questpie"` → `CollectionDoc<"toys">` | Type-only import. See cycle rules below |
-| 2 | Own row inside `.access()` / `.hooks()` | Nothing — `ctx.data` / `ctx.input` are already typed by the builder | Never name your own doc type inside the defining collection |
-| 3 | Shared access-helper parameter | Collection-imported helper: `AccessContext` from `"questpie"`. Anywhere else: `AccessRuleContext<"posts">` from `#questpie` (narrows `ctx.data`) | See cycle rules below |
-| 4 | Shared hook-helper parameter | `HookContext` from `"questpie"` (collection-imported) or `HookRuleContext<"posts">` from `#questpie` | Same rules as #3 |
-| 5 | App/services in a function without a ctx param | `getContext<App>()` with `import type { App } from "#questpie"` | Type-only `App` import — no runtime cycle |
-| 6 | Global doc | `import type { GlobalDoc } from "#questpie"` → `GlobalDoc<"siteSettings">` | Same cycle rules as `CollectionDoc` |
-| 7 | Session / user shape | In handlers: `ctx.session?.user` is typed. Standalone: `import type { AppSession, AppSessionUser } from "#questpie"` | Generated from the app auth config |
-| 8 | Route input/output in the handler | Nothing — inferred from `.schema()` / return type | |
-| 9 | Route input/output standalone | `InferRouteInput<typeof def>` / `InferRouteOutput<typeof def>` / `InferRouteParams<typeof def>` from `questpie/types` | tRPC-style; `def` is the route file's default export |
-| 10 | Client-side types | `createClient<AppConfig>()` — everything flows from the generic | See `references/tanstack-query.md` |
-| 11 | Job payload in the handler | Nothing — `payload` is typed from `schema` | |
-| 12 | Job payload standalone | `InferJobPayload<typeof jobDef>` from `questpie/queue` (or `z.infer<typeof jobDef.schema>`) | |
-| 13 | `db` / `session` inside job/workflow handlers | Honest gap: generated job context types them `unknown` today | Use `collections` (typed) or narrow explicitly; do not restate schemas |
-| 14 | Publishing jobs outside job files | `ctx.queue.<name>.publish(payload)` — payload typed | |
-| 15 | Relation target autocomplete | Nothing — codegen populates `Questpie.CollectionKeys` from discovered files; `f.relation("…")` autocompletes after `questpie generate` | Plain strings always compile |
-| 16 | Realtime payloads | `live()` / `liveIter()` snapshots are typed; raw `client.realtime.subscribe` data is untyped — annotate with `CollectionDoc<"posts">` | Typed realtime contract is planned |
-| 17 | Env vars | `env.ts` / `env.client.ts` with `env()` — see `references/env.md` | Never `process.env.X!` |
-| 18 | Field-level rule ctx (`.access({ fields })`) | `doc` is typed as the row, `user` is typed from the generated session — destructure, don't annotate | |
-| 19 | Derived request context (tenant, role) | `appConfig({ context })` result is inferred and arrives flat on rules — see `references/rules.md` | |
-| 20 | Select-option unions | `CollectionDoc<"events">["type"]` (server-side) | No client-safe union export yet; clients infer from SDK responses |
-
-## The Two Cycle Rules
-
-Type inference flows through the generated index (`#questpie`), and collections are part of that graph. Two rules keep every inference path compiling:
-
-**Rule 1 — inside the defining collection, trust builder inference.** `ctx.data` and `ctx.input` are already typed per operation (table below). Naming your own doc type (`CollectionDoc<"production_orders">` inside `collections/production-orders.ts`, or `ctx.data as OrderDoc`) forces TypeScript to resolve `typeof <own default export>` while that export's type is still being inferred — TS2456/TS7022, or worse, a silently degraded type.
-
-**Rule 2 — helpers imported by collections must not import generated aliases, and must cut the inference loop with an explicit return annotation.** The verified pattern (from `examples/toy-factory-backend/src/questpie/server/lib/access.ts`):
-
-```ts
-// lib/access.ts — imported by a collection, so:
-//  - the helper param is the package-level AccessContext (cycle-safe)
-//  - the return type is annotated explicitly with a CROSS-collection
-//    CollectionDoc (type-only) — this cut breaks the inference loop that
-//    otherwise forms when the helper dereferences ctx.collections back
-//    into the module graph (TS7022/TS2502 without it)
-import type { AccessContext } from "questpie";
-import type { CollectionDoc } from "#questpie";
-
-export async function resolveOrderToy(
-	ctx: AccessContext,
-	toyId: string,
-): Promise<{ toy: CollectionDoc<"toys"> | null; userId: string | null }> {
-	const toy = await ctx.collections.toys.findOne(
-		{ where: { id: toyId } },
-		{ accessMode: "system" },
-	);
-	return { toy, userId: ctx.session?.user.id ?? null };
-}
-
-/** Narrow `data` structurally when the helper only reads a few fields. */
-export function canCancelOrder(ctx: AccessContext<{ priority?: string | null }>) {
-	if (ctx.data?.priority === "rush") return !!ctx.session?.user;
-	return true;
-}
-```
-
-`ctx.app`, `ctx.collections`, and `ctx.session` are fully typed on `AccessContext` through the (lazily merged) AppContext augmentation — the explicit return annotation stays mandatory in collection-imported helpers (it cuts the inference loop).
-
-Helpers **not** imported by any collection (scripts, routes, services, jobs) may freely use `CollectionDoc<K>` in parameters and locals — Rule 2 only binds files that collections import.
-
-## Per-Operation Access Rule Typing
-
-`.access()` rules are typed per operation by the builder — no annotations, no casts:
-
-| Rule | `ctx.data` | `ctx.input` |
-| --- | --- | --- |
-| `read` | not loaded (return `AccessWhere` to filter) | — |
-| `create` | — (no row exists yet) | typed insert shape (pre-validation) |
-| `update` | the existing row — **non-optional** | typed update patch |
-| `delete` | the existing row — **non-optional** | — |
-| `transition` / `serve` | the existing row — non-optional | — |
-
-```ts
-export default collection("production_orders")
-	.fields(({ f }) => ({
-		toy: f.relation("toys").required(),
-		priority: f.select([{ value: "normal" }, { value: "rush" }]),
-	}))
-	.access({
-		create: ({ session, input }) => !!session && input?.priority !== "rush",
-		update: async (ctx) => {
-			ctx.data;  // typed row, non-optional — no `as` cast, no isRecord() dance
-			ctx.input; // typed patch
-			return (await resolveOrderToy(ctx, ctx.data.toy)).userId !== null;
-		},
-	});
-```
-
-The package-level helper types are exported from `questpie/types` (also re-exported from `questpie`): `AccessContext`, `RowAccessRule`, `AccessRule`, `AccessWhere`, `CollectionAccess`, `HookContext`, `FieldAccessRule`, `FieldAccessRuleContext`.
-
-## Typed `getContext<App>()`
-
-For functions that need the app without threading a ctx parameter (and for Better Auth callbacks — see `references/auth.md`):
-
-```ts
-import { getContext } from "questpie";
-import type { App } from "#questpie"; // type-only — no runtime cycle
-
-async function logActivity(action: string) {
-	const { app, session, locale } = getContext<App>();
-	await app.collections.activity_log.create({
-		user: session?.user.id,
-		action,
-		locale,
-	});
-}
-```
-
-Untyped `getContext()` returns the bare context; the `<App>` generic types `app`, `session`, and the derived request-context extensions.
-
-## Standalone Route And Job Types
-
-```ts
-import type { InferRouteInput, InferRouteOutput } from "questpie/types";
-import type { InferJobPayload } from "questpie/queue";
-import createBooking from "../routes/create-booking";
-import sendReminder from "../jobs/send-reminder";
-
-type BookingInput = InferRouteInput<typeof createBooking>;
-type BookingResult = InferRouteOutput<typeof createBooking>;
-type ReminderPayload = InferJobPayload<typeof sendReminder>;
-```
-
-## Key Registries (Advanced, Optional)
-
-Names-only registries give `f.relation()` target autocomplete without entering the type graph (no imports — they cannot cycle). Codegen does **not** populate them yet; augment manually when you want the autocomplete:
-
-```ts
-// types/questpie-keys.d.ts (any ambient file)
-declare global {
-	namespace Questpie {
-		interface CollectionKeys { toys: unknown; production_orders: unknown }
-		interface GlobalKeys { factorySettings: unknown }
-		interface JobKeys { sendReminder: unknown }
-	}
-}
-export {};
-```
-
-`f.relation("toys")` then autocompletes, while arbitrary strings keep compiling (`(string & {})` fallback) — this is autocomplete, not strictness. `KnownCollectionKey` / `KnownGlobalKey` / `KnownJobKey` from `questpie/types` consume the registries in your own signatures.
-
-## Escape Hatches (When Inference Needs Help)
-
-For columns whose value type the field cannot infer, stay declarative — see `references/field-types.md`:
-
-- `.zod(schema)` — type **and** runtime validation (preferred for `f.json()`)
-- `.$type<T>()` — type-only narrowing
-- `.drizzle(fn)` — raw column builder; `$type` on it narrows the value type
-
-## Never Do
-
-| Anti-pattern | Why | Instead |
-| --- | --- | --- |
-| Hand-rolled `EventDoc = { id: string; ownerUser?: string }` | Silent nullability drift vs the real schema | `CollectionDoc<"events">` (row 1) |
-| `ctx.data as MemberDoc` inside own `.access()` | Builder already types it; self-key casts can cycle (TS2456) | Trust `ctx.data` (row 2) |
-| Hand-rolled `CollectionsLike` / `AccessRuleCtx` ctx mirrors | Structural matching of CRUD generics → deep error walls, tsc 5.9 crashes | `AccessContext` param (row 3) |
-| Module-level `app` singleton for callbacks | Import cycles; stale instance in tests | `getContext<App>()` (row 5) |
-| Collection-imported helper returning unannotated `ctx.collections` results | TS7022/TS2502 self-reference | Explicit return annotation (Rule 2) |

package/skills/questpie/references/workflows.md

@@ -1,155 +0,0 @@
----
-name: questpie-core/workflows
-description:
-  QUESTPIE durable workflows long-running business processes replay steps sleep waitForEvent invoke compensation cron admin UI workflow service
-  - questpie-core
----
-
-# Durable Workflows
-
-Use `@questpie/workflows` when business logic spans multiple steps, waits on time or external events, needs retry-safe side effects, or should survive process restarts.
-
-## Install And Register
-
-```bash
-bun add @questpie/workflows
-```
-
-```ts title="modules.ts"
-import { workflowsModule } from "@questpie/workflows/modules/workflows";
-export default [workflowsModule] as const;
-```
-
-`workflowsModule` carries its codegen plugin. Do not also add `workflowsPlugin()` to `questpie.config.ts` unless you are doing a custom module setup that deliberately omits `workflowsModule`.
-
-Runtime options (route access rule — default admin-only — and execution-lease settings) go in plugin-discovered `config/workflows.ts` using the `workflowsConfig()` factory from `@questpie/workflows/server`.
-
-For admin UI pages/widgets, register the client module:
-
-```ts title="questpie/admin/modules.ts"
-import adminClientModule from "@questpie/admin/client-module";
-import { workflowsClientModule } from "@questpie/workflows/client/modules/workflows";
-export default {
-	name: "app-admin" as const,
-	views: { ...adminClientModule.views, ...workflowsClientModule.views },
-	components: {
-		...adminClientModule.components,
-		...workflowsClientModule.components,
-	},
-	fields: { ...adminClientModule.fields, ...workflowsClientModule.fields },
-	pages: { ...adminClientModule.pages, ...workflowsClientModule.pages },
-	widgets: { ...adminClientModule.widgets, ...workflowsClientModule.widgets },
-	blocks: { ...adminClientModule.blocks, ...workflowsClientModule.blocks },
-};
-```
-
-## Define A Workflow
-
-Put workflow definitions in `workflows/*.ts`:
-
-```ts title="workflows/production-order.ts"
-import { workflow } from "@questpie/workflows";
-import { z } from "zod";
-
-export default workflow({
-	name: "production-order",
-	schema: z.object({
-		orderId: z.string(),
-	}),
-	timeout: "7d",
-	handler: async ({ input, step, ctx, log }) => {
-		const order = await step.run("load-order", async () => {
-			return ctx.collections.productionOrders.findOne({
-				where: { id: input.orderId },
-				with: { toy: true },
-			});
-		});
-		if (!order) throw new Error("Production order not found");
-
-		await step.run("reserve-materials", async () => {
-			await ctx.queue.recalculateMaterialPlan.publish({
-				orderId: input.orderId,
-			});
-		});
-
-		await step.waitForEvent("materials-ready", {
-			event: "materials.available",
-			match: { orderId: input.orderId },
-			timeout: "2d",
-		});
-
-		await step.run("notify-scheduled", async () => {
-			await ctx.email.sendTemplate({
-				template: "productionScheduled",
-				input: { orderId: input.orderId },
-				to: order.ownerEmail,
-			});
-		});
-
-		log.info("Production order workflow completed");
-		return { status: "scheduled" };
-	},
-});
-```
-
-Run codegen after adding workflow files:
-
-```bash
-bun questpie generate
-```
-
-## Trigger And Signal
-
-Use injected `workflows` from route, job, hook, or service context:
-
-```ts title="routes/start-production.ts"
-import { route } from "questpie/services";
-import { z } from "zod";
-
-export default route()
-	.post()
-	.schema(z.object({ orderId: z.string() }))
-	.handler(async ({ input, workflows }) => {
-		const result = await workflows.trigger("production-order", {
-			orderId: input.orderId,
-		});
-		return { instanceId: result.instanceId };
-	});
-```
-
-Signal waiting workflows:
-
-```ts
-await workflows.sendEvent(
-	"materials.available",
-	{ receivedAt: new Date().toISOString() },
-	{ orderId },
-);
-```
-
-## Cron Workflows
-
-Use workflow-level `cron` for recurring long-running processes:
-
-```ts
-export default workflow({
-	name: "nightly-material-plan",
-	schema: z.object({}),
-	cron: { schedule: "0 2 * * *", overlap: "skip" },
-	handler: async ({ step, ctx }) => {
-		await step.run("recalculate", async () => {
-			await ctx.queue.recalculateMaterialPlan.publish({});
-		});
-	},
-});
-```
-
-On Node/Bun workers, `app.queue.listen()` runs workflow jobs and maintenance. On Cloudflare Workers, use `cloudflareQueuesAdapter`, export `createCloudflareWorkerHandlers(app)`, and configure a Cron Trigger for workflow maintenance.
-
-## Rules
-
-- Keep external side effects inside `step.run()` so replay does not repeat them.
-- Use stable step names. Renaming a step changes replay identity.
-- Use idempotency keys when calling external APIs.
-- Use `step.waitForEvent()` for durable waits instead of polling loops.
-- Keep workflow definitions in `workflows/`; do not define them inside route/job files.