content-query 0.3.0 → 0.5.0

package/dist/{relational-types-B45zM34W.d.mts → relational-types-CTcalUNW.d.mts}

@@ -1,4 +1,4 @@
-import { c as Relationship, i as CollectionRegistry, l as RelationshipsOf, o as PayloadsOf, s as QueryData } from "./types-BC8gVJ6u.mjs";
+import { S as UnavailableRelationshipsOf, T as VariantOf, _ as Relationship, g as QueryData, h as PayloadsOf, i as CollectionRegistry, v as RelationshipsOf, x as UnavailableRelationship } from "./types-Dz1vTXa2.mjs";
 //#region src/query/plan.d.ts
 type PredicateOperator = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in-array" | "not-in-array" | "contains" | "starts-with" | "ends-with" | "like" | "ilike" | "array-contains" | "array-contains-any" | "array-contains-all" | "array-contained" | "is-null" | "is-undefined" | "is-missing";
 type Expression = {
@@ -12,15 +12,20 @@ type Expression = {
   field: string;
   target: string;
   expression: Expression;
+} |
+/** A fluent `has()` filter that query builders resolve into a `relation` expression. */
+{
+  kind: "has";
+  field: string;
+  expression: Expression;
 } | {
   kind: "and" | "or" | "not";
   expressions: readonly Expression[];
 };
 type QueryPlan = {
   collection: string;
+  /** Explicitly selected fields; scopes never include unselected fields, including `id`. */
   select?: readonly string[];
-  allFields?: boolean;
-  exclude?: readonly string[];
   filters: readonly Expression[];
   order: readonly {
     field: string;
@@ -29,14 +34,45 @@ type QueryPlan = {
   limit?: number;
   offset?: number;
   with: Readonly<Record<string, QueryPlan>>;
-  adjacent?: true | QueryPlan;
+  adjacent?: AdjacentPlan;
   /** Payloads to attach under `_payloads` after filtering, ordering, and pagination. */
   payloads?: Readonly<Record<string, PlanPayload>>;
+  /** A root `paginate()` request; plans that carry it never set `limit` or `offset`. */
+  paginate?: PaginatePlan;
+};
+/**
+ * A page-number or cursor page request. Cursor keys are already decoded into the sort values of the
+ * boundary entry, in effective-order position, so backends never parse cursor strings.
+ */
+type PaginatePlan = {
+  mode: "page";
+  page: number;
+  size: number;
+} | {
+  mode: "cursor";
+  size: number;
+  /** `after` pages forward from `key`; `before` pages backward to it. */
+  direction: "after" | "before";
+  /** Sort values of the boundary entry; omitted to start at the first or last entry. */
+  key?: readonly unknown[];
+  /** Whether the result includes the filtered total. */
+  total: boolean;
+};
+/**
+ * Selects previous and next entries. `results` finds neighbors within the scope's own filtered and
+ * ordered entries, or a parent's related entries, and `plan` holds only their selection;
+ * `collection` finds neighbors in an independent sibling scope described by `plan`.
+ */
+type AdjacentPlan = {
+  scope: "results" | "collection";
+  plan: QueryPlan;
 };
 /** One requested payload; variant keys are empty for payloads without variants. */
 type PlanPayload = {
   variant: Readonly<Record<string, string>>;
 };
+/** How a plan returns its results; `paginate` requires the plan's `paginate` request. */
+type QueryTerminal = "all" | "first" | "count" | "paginate";
 /** Describes a payload that queries may request, without its resolver or schema. */
 type PayloadDescriptor = {
   variants: readonly string[];
@@ -45,16 +81,41 @@ type QueryRegistry = Record<string, {
   relationships: Record<string, Relationship>;
   /** Payload names available to queries; omitted when the collection has none. */
   payloads?: Record<string, PayloadDescriptor>;
+  /**
+   * Declared relationships whose target collection this query scope has not loaded, by name, with
+   * the target collection. Queries that use one report which collection to pass to `using()`.
+   */
+  unavailable?: Record<string, string>;
+  /** The declared `typeName`, which only generated declarations read. */
+  typeName?: string;
 }>;
+/** Explains the explicit-selection rule wherever a scope returns rows without selecting data. */
+declare const NO_SELECTION_MESSAGE: "Select fields, relationships, payloads, or adjacent entries before running this query.";
+/** Explains why `paginate()` is unavailable once a query sets its own limit or offset. */
+declare const PAGINATE_AFTER_LIMIT_MESSAGE: "paginate() sets the limit and offset itself; remove limit and offset from this query.";
 //#endregion
 //#region src/query/types.d.ts
 declare const queryType: unique symbol;
+/** Running an unselected query reports the explicit-selection rule as its required `this` type. */
+type UnselectedTerminal = (this: typeof NO_SELECTION_MESSAGE, ...arguments_: readonly unknown[]) => never;
+/** A `then` that cannot resolve a value, so awaiting an unselected query fails to compile. */
+type UnselectedThen = (selectBeforeAwaiting: typeof NO_SELECTION_MESSAGE) => never;
 declare const fieldType: unique symbol;
 type Field$1<Value> = {
   readonly name: string;
   readonly [fieldType]: Value;
 };
 type Fields<Data> = { readonly [Name in keyof Data]-?: Field$1<Data[Name]>; };
+declare const relationTarget: unique symbol;
+/** A relationship in a fluent `where()` callback, filtered with `has()`. */
+type RelationField<TargetFields> = {
+  readonly name: string;
+  readonly [relationTarget]: TargetFields;
+};
+/** Fields and relationships available to a fluent `where()` callback. */
+type QueryFields<Registry extends CollectionRegistry, Name extends keyof Registry & string> = Fields<QueryData<Registry[Name]>> & { readonly [Key in keyof RelationshipsOf<Registry[Name]> & string]-?: RelationField<QueryFields<Registry, RelatedName$1<Registry, RelationOf<Registry, Name, Key>>>>; } & { readonly [
+/** A relationship into a collection the query has not loaded reads as the type error. */
+Key in keyof UnavailableRelationshipsOf<Registry[Name]> & string]-?: UnavailableRelationship<Registry[Name], Key>; };
 type Scalar = string | number | bigint | boolean | Date | null | undefined;
 type ScalarField<Value> = Field$1<Value> & ([Value] extends [Scalar] ? unknown : never);
 type Ordered<Value> = NonNullable<Value> extends string ? unknown : NonNullable<Value> extends number ? unknown : NonNullable<Value> extends bigint ? unknown : NonNullable<Value> extends Date ? unknown : never;
@@ -80,39 +141,112 @@ type RelatedName$1<Registry extends CollectionRegistry, Relation extends Relatio
 /** Applies declared relationship cardinality, optional reference fields, and filtering to a result. */
 type RelationshipResult<Definition, Relation extends Relationship, Result, Filtered extends boolean = false> = Relation["type"] extends "many" ? Result[] : Result | (Filtered extends true ? null : Relation["referenceSide"] extends "from" ? Relation["from"] extends keyof QueryData<Definition> ? null extends QueryData<Definition>[Relation["from"]] ? null : undefined extends QueryData<Definition>[Relation["from"]] ? null : never : null : null);
 type RelationValue<Definition, Relation extends Relationship, Configured> = RelationshipResult<Definition, Relation, ResultOf<Configured>, FilteredOf<Configured>>;
-type Query<Registry extends CollectionRegistry, Name extends keyof Registry & string, Result = {}, Selected extends boolean = false, Many extends boolean = true, Root extends boolean = true, Filtered extends boolean = false, AllowAdjacent extends boolean = true, Pagination extends boolean = true> = QueryInfo<Result, Selected, Filtered> & {
-  select<const Keys extends readonly [keyof QueryData<Registry[Name]> & string, ...(keyof QueryData<Registry[Name]> & string)[]]>(...keys: Keys): Query<Registry, Name, { [Key in Exclude<keyof Result, keyof QueryData<Registry[Name]>> | Keys[number]]: Key extends Keys[number] ? QueryData<Registry[Name]>[Key & keyof QueryData<Registry[Name]>] : Key extends keyof Result ? Result[Key] : never; }, true, Many, Root, Filtered, AllowAdjacent, Pagination>;
-  where(configure: (fields: Fields<QueryData<Registry[Name]>>) => Expression): Query<Registry, Name, Result, Selected, Many, Root, true, AllowAdjacent, Pagination>;
-  with<Key extends keyof RelationshipsOf<Registry[Name]> & string, Configured extends QueryInfo<unknown, true>>(name: Key, configure: (query: Query<Registry, RelatedName$1<Registry, RelationOf<Registry, Name, Key>>, {}, false, RelationOf<Registry, Name, Key>["type"] extends "many" ? true : false, false, false, AllowAdjacent>) => Configured): Query<Registry, Name, Result & { [Property in Key]: RelationValue<Registry[Name], RelationOf<Registry, Name, Key>, Configured>; }, true, Many, Root, Filtered, AllowAdjacent, Pagination>;
+type Query<Registry extends CollectionRegistry, Name extends keyof Registry & string, Result = {}, Selected extends boolean = false, Many extends boolean = true, Root extends boolean = true, Filtered extends boolean = false, AllowAdjacent extends boolean = true, Pagination extends boolean = true, Paged extends boolean = false> = QueryInfo<Result, Selected, Filtered> & {
+  select<const Keys extends readonly [keyof QueryData<Registry[Name]> & string, ...(keyof QueryData<Registry[Name]> & string)[]]>(...keys: Keys): Query<Registry, Name, { [Key in Exclude<keyof Result, keyof QueryData<Registry[Name]>> | Keys[number]]: Key extends Keys[number] ? QueryData<Registry[Name]>[Key & keyof QueryData<Registry[Name]>] : Key extends keyof Result ? Result[Key] : never; }, true, Many, Root, Filtered, AllowAdjacent, Pagination, Paged>;
+  where(configure: (fields: QueryFields<Registry, Name>) => Expression): Query<Registry, Name, Result, Selected, Many, Root, true, AllowAdjacent, Pagination, Paged>;
+  with<Key extends keyof RelationshipsOf<Registry[Name]> & string, Configured extends QueryInfo<unknown, true>>(name: Key, configure: (query: Query<Registry, RelatedName$1<Registry, RelationOf<Registry, Name, Key>>, {}, false, RelationOf<Registry, Name, Key>["type"] extends "many" ? true : false, false, false, AllowAdjacent>) => Configured): Query<Registry, Name, Result & { [Property in Key]: RelationValue<Registry[Name], RelationOf<Registry, Name, Key>, Configured>; }, true, Many, Root, Filtered, AllowAdjacent, Pagination, Paged>;
+  /** A relationship into a collection the query has not loaded reports which one to supply. */
+  with<Key extends keyof UnavailableRelationshipsOf<Registry[Name]> & string>(name: Key, configure: UnavailableRelationship<Registry[Name], Key>): never;
 } & (Many extends true ? {
-  orderBy(field: SortKey<QueryData<Registry[Name]>>, direction?: "asc" | "desc"): Query<Registry, Name, Result, Selected, Many, Root, Filtered, AllowAdjacent, Pagination>;
+  orderBy(field: SortKey<QueryData<Registry[Name]>>, direction?: "asc" | "desc"): Query<Registry, Name, Result, Selected, Many, Root, Filtered, AllowAdjacent, Pagination, Paged>;
 } : {}) & (Many extends true ? Pagination extends true ? {
-  limit(value: number): Query<Registry, Name, Result, Selected, Many, Root, Filtered, AllowAdjacent, Pagination>;
-  offset(value: number): Query<Registry, Name, Result, Selected, Many, Root, Filtered, AllowAdjacent, Pagination>;
+  limit(value: number): Query<Registry, Name, Result, Selected, Many, Root, Filtered, AllowAdjacent, Pagination, true>;
+  offset(value: number): Query<Registry, Name, Result, Selected, Many, Root, Filtered, AllowAdjacent, Pagination, true>;
 } : {} : {}) & (AllowAdjacent extends true ? {
   /** Attaches a payload under `_payloads` after filtering, ordering, and pagination. */
-  withPayload<Key extends keyof PayloadsOf<Registry[Name]> & string>(name: Key): Query<Registry, Name, WithPayload<Result, Key, PayloadsOf<Registry[Name]>[Key]>, Selected, Many, Root, Filtered, AllowAdjacent, Pagination>;
-  selectAdjacent(): Query<Registry, Name, Result & {
-    _adjacent: Adjacent<{
-      id: string;
-    }>;
-  }, true, Many, Root, Filtered, AllowAdjacent, Pagination>;
+  withPayload<Key extends keyof PayloadsOf<Registry[Name]> & string>(name: Key, ...variant: keyof VariantOf<Registry[Name], Key> extends never ? [] : [variant: Readonly<VariantOf<Registry[Name], Key>>]): Query<Registry, Name, WithPayload<Result, Key, PayloadsOf<Registry[Name]>[Key]>, true, Many, Root, Filtered, AllowAdjacent, Pagination, Paged>;
+  /** Selects neighbor fields within this scope's filtered and ordered results. */
+  selectAdjacent<const Keys extends readonly [keyof QueryData<Registry[Name]> & string, ...(keyof QueryData<Registry[Name]> & string)[]]>(...fields: Keys): Query<Registry, Name, Result & {
+    _adjacent: Adjacent<{ [Key in Keys[number]]: QueryData<Registry[Name]>[Key & keyof QueryData<Registry[Name]>]; }>;
+  }, true, Many, Root, Filtered, AllowAdjacent, Pagination, Paged>;
   selectAdjacent<Configured extends QueryInfo<unknown, true>>(configure: (siblings: Query<Registry, Name, {}, false, true, false, false, false, false>) => Configured): Query<Registry, Name, Result & {
     _adjacent: Adjacent<ResultOf<Configured>>;
-  }, true, Many, Root, Filtered, AllowAdjacent, Pagination>;
+  }, true, Many, Root, Filtered, AllowAdjacent, Pagination, Paged>;
   selectAdjacent<const Options extends AdjacentOptions<Registry, Name>>(options: Options & CheckedOptions<Registry, Name, NoInfer<Options>, true, false, false>): Query<Registry, Name, Result & {
     _adjacent: Adjacent<SelectionResult<Registry, Name, Options["select"]>>;
-  }, true, Many, Root, Filtered, AllowAdjacent, Pagination>;
+  }, true, Many, Root, Filtered, AllowAdjacent, Pagination, Paged>;
 } : {}) & (Root extends true ? {
-  all: Selected extends true ? () => Promise<Simplify$1<Result>[]> : never;
-  execute: Selected extends true ? () => Promise<Simplify$1<Result>[]> : never;
-  then: Selected extends true ? Promise<Simplify$1<Result>[]>["then"] : never;
-  first: Selected extends true ? () => Promise<Simplify$1<Result> | undefined> : never;
-  /** Counts matching entries; unavailable once payloads are requested. */
+  all: Selected extends true ? () => Promise<Simplify$1<Result>[]> : UnselectedTerminal;
+  execute: Selected extends true ? () => Promise<Simplify$1<Result>[]> : UnselectedTerminal;
+  then: Selected extends true ? Promise<Simplify$1<Result>[]>["then"] : UnselectedThen;
+  first: Selected extends true ? () => Promise<Simplify$1<Result> | undefined> : UnselectedTerminal;
+  /** Counts matching entries without a selection; unavailable once payloads are requested. */
   count: [Result] extends [never] ? () => Promise<number> : [Result] extends [{
     _payloads: unknown;
   }] ? never : () => Promise<number>;
+  /**
+   * Returns one page from one revision: `{ page, size }` for page numbers, or
+   * `{ size, after?, before?, total? }` for cursors. Unavailable after `limit()` or `offset()`.
+   */
+  paginate: Selected extends true ? [Paged] extends [true] ? PaginateAfterLimit : Paginate<Simplify$1<Result>> : UnselectedTerminal;
 } : {});
+/** `paginate()` after `limit()` or `offset()` reports why as its required `this` type. */
+type PaginateAfterLimit = (this: typeof PAGINATE_AFTER_LIMIT_MESSAGE, ...arguments_: readonly unknown[]) => never;
+/** The `paginate()` overloads for one item type. */
+type Paginate<Item> = {
+  (options: PageOptions): Promise<NumberedPage<Item>>;
+  (options: CursorOptions & {
+    total: true;
+  }): Promise<CursorPage<Item, true>>;
+  (options: CursorOptions): Promise<CursorPage<Item>>;
+};
+/** Page-number pagination: `page` starts at 1 and `size` is the number of entries per page. */
+type PageOptions = {
+  page: number;
+  size: number;
+  after?: never;
+  before?: never;
+  total?: never;
+};
+/**
+ * Cursor pagination. `after` continues from an earlier page's `endCursor`; `before` returns the
+ * entries just before a `startCursor`. A `null` cursor starts at the first entry (`after`) or the
+ * last entry (`before`). `total: true` adds the matching total.
+ */
+type CursorOptions = {
+  size: number;
+  page?: never;
+  total?: boolean;
+} & ({
+  after?: string | null;
+  before?: never;
+} | {
+  before?: string | null;
+  after?: never;
+});
+/** Options accepted by `paginate()`. */
+type PaginateOptions = PageOptions | CursorOptions;
+/** Option names that `paginate()` reads alongside relational query options. */
+type PaginateKey = keyof PageOptions;
+/** One numbered page and where it sits among every matching entry. */
+type NumberedPage<Item> = {
+  items: Item[];
+  /** Matching entries across every page. */
+  total: number;
+  page: number;
+  /** At least 1: the first page exists even when nothing matches. */
+  pageCount: number;
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+};
+/** One cursor page. Both cursors are `null` when the page is empty. */
+type CursorPage<Item, Total extends boolean = false> = {
+  items: Item[];
+  /** Pass as `before` for the previous page. */
+  startCursor: string | null;
+  /** Pass as `after` for the next page. */
+  endCursor: string | null;
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+} & (Total extends true ? {
+  total: number;
+} : {});
+/** The page type `paginate()` returns for the given options. */
+type PaginateResult<Item, Options> = Options extends {
+  page: number;
+} ? NumberedPage<Item> : CursorPage<Item, Options extends {
+  total: true;
+} ? true : false>;
 type Adjacent<Entry> = {
   previous: Entry | null;
   next: Entry | null;
@@ -149,7 +283,7 @@ type Where<Data> = { [Name in keyof Data]?: [Data[Name]] extends [Scalar] ? Data
 };
 type OrderBy<Data> = Partial<Record<SortKey<Data>, "asc" | "desc">>;
 type ObjectScope<Registry extends CollectionRegistry, Name extends keyof Registry & string, Many extends boolean> = {
-  where?: Where<QueryData<Registry[Name]>> | ((fields: Fields<QueryData<Registry[Name]>>) => Expression);
+  where?: Where<QueryData<Registry[Name]>> | ((fields: QueryFields<Registry, Name>) => Expression);
 } & (Many extends true ? {
   orderBy?: OrderBy<QueryData<Registry[Name]>> | readonly OrderBy<QueryData<Registry[Name]>>[];
   limit?: number;
@@ -160,20 +294,27 @@ type QueryOptions<Registry extends CollectionRegistry, Name extends keyof Regist
 };
 type AdjacentOptions<Registry extends CollectionRegistry, Name extends keyof Registry & string> = Omit<QueryOptions<Registry, Name, true, false>, "limit" | "offset">;
 type Selection<Registry extends CollectionRegistry, Name extends keyof Registry & string, AllowAdjacent extends boolean = true> = { [Field in keyof QueryData<Registry[Name]>]?: boolean; } & { [Key in keyof RelationshipsOf<Registry[Name]>]?: QueryOptions<Registry, RelatedName$1<Registry, RelationOf<Registry, Name, Key>>, RelationOf<Registry, Name, Key>["type"] extends "many" ? true : false, AllowAdjacent> | false; } & (AllowAdjacent extends true ? {
-  _adjacent?: true | AdjacentOptions<Registry, Name>;
+  _adjacent?: {
+    scope: "results";
+    select: Selection<Registry, Name, false>;
+  } | (AdjacentOptions<Registry, Name> & {
+    scope?: "collection";
+  });
 } : {});
 type ObjectRelationValue<Registry extends CollectionRegistry, Name extends keyof Registry & string, Key extends keyof RelationshipsOf<Registry[Name]>, Options> = Options extends {
   select: infer Projection;
 } ? RelationValue<Registry[Name], RelationOf<Registry, Name, Key>, QueryInfo<SelectionResult<Registry, RelatedName$1<Registry, RelationOf<Registry, Name, Key>>, Projection>, true, "where" extends keyof Options ? true : false>> : never;
-type SelectionResult<Registry extends CollectionRegistry, Name extends keyof Registry & string, Projection> = { -readonly [Key in keyof Projection as Projection[Key] extends false | undefined ? never : Key]-?: Key extends "_adjacent" ? Projection[Key] extends true ? Adjacent<{
-  id: string;
-}> : Projection[Key] extends {
+type SelectionResult<Registry extends CollectionRegistry, Name extends keyof Registry & string, Projection> = { -readonly [Key in keyof Projection as Projection[Key] extends false | undefined ? never : Key]-?: Key extends "_adjacent" ? Projection[Key] extends {
   select: infer Neighbors;
 } ? Adjacent<SelectionResult<Registry, Name, Neighbors>> : never : Key extends keyof RelationshipsOf<Registry[Name]> ? ObjectRelationValue<Registry, Name, Key, Projection[Key]> : Key extends keyof QueryData<Registry[Name]> ? QueryData<Registry[Name]>[Key] : never; };
 type CheckedField<Value, Filter> = Filter extends Scalar ? Filter : { [Operator in keyof Filter]: Operator extends keyof FieldFilter$1<Value> ? Operator extends "not" ? CheckedField<Value, Filter[Operator]> : Filter[Operator] : never; };
 type CheckedWhereList$1<Data, Filters extends readonly unknown[]> = { [Index in keyof Filters]: CheckedWhere$1<Data, Filters[Index]>; };
 type CheckedWhere$1<Data, Filter> = Filter extends ((...arguments_: never[]) => unknown) ? Filter : { [Key in keyof Filter]: Key extends "AND" | "OR" | "NOT" ? Filter[Key] extends readonly unknown[] ? CheckedWhereList$1<Data, Filter[Key]> : CheckedWhere$1<Data, Filter[Key]> : Key extends keyof Data ? CheckedField<Data[Key], Filter[Key]> : never; };
-type CheckedSelection<Registry extends CollectionRegistry, Name extends keyof Registry & string, Projection, AllowAdjacent extends boolean> = { [Key in keyof Projection]: Key extends "_adjacent" ? AllowAdjacent extends true ? Projection[Key] extends true ? true : CheckedOptions<Registry, Name, Projection[Key], true, false, false> : never : Key extends keyof RelationshipsOf<Registry[Name]> ? Projection[Key] extends false ? false : CheckedOptions<Registry, RelatedName$1<Registry, RelationOf<Registry, Name, Key>>, Projection[Key], RelationOf<Registry, Name, Key>["type"] extends "many" ? true : false, AllowAdjacent> : Key extends keyof QueryData<Registry[Name]> ? Projection[Key] : never; };
+type CheckedSelection<Registry extends CollectionRegistry, Name extends keyof Registry & string, Projection, AllowAdjacent extends boolean> = { [Key in keyof Projection]: Key extends "_adjacent" ? AllowAdjacent extends true ? Projection[Key] extends {
+  scope: "results";
+} ? { [Option in keyof Projection[Key]]: Option extends "scope" ? "results" : Option extends "select" ? CheckedSelection<Registry, Name, Projection[Key][Option], false> : never; } : CheckedOptions<Registry, Name, Omit<Projection[Key], "scope">, true, false, false> & {
+  scope?: "collection";
+} : never : Key extends keyof RelationshipsOf<Registry[Name]> ? Projection[Key] extends false ? false : CheckedOptions<Registry, RelatedName$1<Registry, RelationOf<Registry, Name, Key>>, Projection[Key], RelationOf<Registry, Name, Key>["type"] extends "many" ? true : false, AllowAdjacent> : Key extends keyof QueryData<Registry[Name]> ? Projection[Key] : never; };
 /** Rejects extra properties throughout inferred options, including recursive neighbor projections. */
 type CheckedOptions<Registry extends CollectionRegistry, Name extends keyof Registry & string, Options, Many extends boolean = true, AllowAdjacent extends boolean = true, Pagination extends boolean = true> = { [Key in keyof Options]: Key extends "select" ? CheckedSelection<Registry, Name, Options[Key], AllowAdjacent> : Key extends "where" ? CheckedWhere$1<QueryData<Registry[Name]>, Options[Key]> : Key extends "limit" | "offset" ? Pagination extends true ? Many extends true ? Options[Key] : never : never : Key extends keyof ObjectScope<Registry, Name, Many> ? Options[Key] : never; };
 //#endregion
@@ -221,36 +362,71 @@ type RelationalWhere<Registry extends CollectionRegistry, Name extends keyof Reg
   NOT?: RelationalWhere<Registry, Name> | readonly RelationalWhere<Registry, Name>[];
   RAW?: (fields: Fields<QueryData<Registry[Name]>>) => Expression;
 };
+/** Requests one payload: `true` without variants, or a record giving every variant key. */
+type PayloadRequest<Variant> = keyof Variant extends never ? true : Readonly<Variant>;
 /** Payloads to attach under `_payloads`; payloads set to false are omitted. */
-type PayloadOptions<Registry extends CollectionRegistry, Name extends keyof Registry & string> = { [Key in keyof PayloadsOf<Registry[Name]>]?: boolean; };
-/** Collection-scoped metadata queries with Drizzle-style columns, relationships, and filters. */
+type PayloadOptions<Registry extends CollectionRegistry, Name extends keyof Registry & string> = { [Key in keyof PayloadsOf<Registry[Name]>]?: false | PayloadRequest<VariantOf<Registry[Name], Key>>; };
+/** Rejects variant keys a payload does not declare, including through inferred variables. */
+type CheckedPayloadRequest<Request, Variant> = Request extends boolean ? Request : { [Key in keyof Request]: Key extends keyof Variant ? string : never; };
+/**
+ * Collection-scoped metadata queries with Drizzle-style columns, relationships, and filters.
+ * Nothing is selected implicitly, not even `id`: list fields in `columns`, include relationships
+ * with nested options, request payloads, or select adjacency.
+ */
 type RelationalQueryOptions<Registry extends CollectionRegistry, Name extends keyof Registry & string, Many extends boolean = true, AllowAdjacent extends boolean = true, Pagination extends boolean = true> = {
-  columns?: Partial<Record<keyof QueryData<Registry[Name]>, boolean>>;
+  /** Fields to include, each set to `true`. Omitted fields are never returned. */
+  columns?: Partial<Record<keyof QueryData<Registry[Name]>, true>>;
   where?: RelationalWhere<Registry, Name>;
-  with?: { [Key in keyof RelationshipsOf<Registry[Name]>]?: boolean | RelationalQueryOptions<Registry, RelatedName<Registry, Name, Key>, IsMany<Registry, Name, Key>, AllowAdjacent>; };
+  /** Related entries to include; each selects its own data. `false` omits a relationship. */
+  with?: { [Key in keyof RelationshipsOf<Registry[Name]>]?: false | RelationalQueryOptions<Registry, RelatedName<Registry, Name, Key>, IsMany<Registry, Name, Key>, AllowAdjacent>; };
 } & (Many extends true ? {
   orderBy?: OrderBy<QueryData<Registry[Name]>>;
 } : {}) & (Many extends true ? (Pagination extends true ? {
   limit?: number;
   offset?: number;
 } : {}) : {}) & (AllowAdjacent extends true ? {
-  adjacent?: true | RelationalQueryOptions<Registry, Name, true, false, false>;
+  /**
+   * Previous and next entries, which select their own data. `scope: "results"` finds
+   * neighbors within these results; other options describe an independent sibling scope.
+   */
+  adjacent?: ({
+    scope: "results";
+  } & Pick<RelationalQueryOptions<Registry, Name, true, false, false>, "columns" | "with">) | ({
+    scope?: "collection";
+  } & RelationalQueryOptions<Registry, Name, true, false, false>);
   payloads?: PayloadOptions<Registry, Name>;
 } : {});
+/** Options accepted by relational `paginate()`: query options without limit or offset, plus a page request. */
+type RelationalPaginateOptions<Registry extends CollectionRegistry, Name extends keyof Registry & string> = RelationalQueryOptions<Registry, Name, true, true, false> & PaginateOptions;
 /** Options accepted by the root count helper, whose result ignores sorting and pagination. */
 type RelationalCountOptions<Registry extends CollectionRegistry, Name extends keyof Registry & string> = Pick<RelationalQueryOptions<Registry, Name>, "where" | "orderBy" | "offset" | "limit">;
 type ColumnResult<Data, Options> = Options extends {
   columns: infer Columns;
-} ? keyof Columns extends never ? {} : true extends Columns[keyof Columns] ? { -readonly [Key in keyof Columns as Columns[Key] extends false | undefined ? never : Key]-?: Key extends keyof Data ? Data[Key] : never; } : Omit<Data, { [Key in keyof Columns]: Columns[Key] extends false ? Key : never; }[keyof Columns]> : Data;
+} ? { -readonly [Key in keyof Columns as Columns[Key] extends true ? Key : never]-?: Key extends keyof Data ? Data[Key] : never; } : {};
+/** Keys whose option values request something, as opposed to `false` or `undefined`. */
+type Requested<Map> = keyof { [Key in keyof Map as Map[Key] extends false | undefined ? never : Key]: unknown; };
+/** Whether options select fields, include relationships, request payloads, or select adjacency. */
+type SelectsData<Options> = (Options extends {
+  columns: infer Columns;
+} ? Requested<Columns> : never) | (Options extends {
+  with: infer Related;
+} ? Requested<Related> : never) | (Options extends {
+  payloads: infer Payloads;
+} ? Requested<Payloads> : never) | (Options extends {
+  adjacent: infer Neighbors;
+} ? Neighbors extends false | undefined ? never : "adjacent" : never) extends never ? false : true;
+/**
+ * Requires a row-returning scope to request data. An unselected scope must supply an impossible
+ * property named after the rule, so the compiler error states it.
+ */
+type SelectionRequired<Options> = SelectsData<Options> extends true ? unknown : { [Rule in typeof NO_SELECTION_MESSAGE]: never; };
 type IncludedResult<Registry extends CollectionRegistry, Name extends keyof Registry & string, Options> = Options extends {
   with: infer Related;
-} ? { -readonly [Key in keyof Related as Related[Key] extends false | undefined ? never : Key]-?: Key extends keyof RelationshipsOf<Registry[Name]> ? RelationshipResult<Registry[Name], RelationshipsOf<Registry[Name]>[Key] & Relationship, RelationalQueryResult<Registry, RelatedName<Registry, Name, Key>, Related[Key] extends true ? {} : Related[Key]>, "where" extends keyof Related[Key] ? true : false> : never; } : {};
+} ? { -readonly [Key in keyof Related as Related[Key] extends false | undefined ? never : Key]-?: Key extends keyof RelationshipsOf<Registry[Name]> ? RelationshipResult<Registry[Name], RelationshipsOf<Registry[Name]>[Key] & Relationship, RelationalQueryResult<Registry, RelatedName<Registry, Name, Key>, Related[Key]>, "where" extends keyof Related[Key] ? true : false> : never; } : {};
 type AdjacentResult<Registry extends CollectionRegistry, Name extends keyof Registry & string, Options> = Options extends {
   adjacent: infer Neighbors;
 } ? {
-  _adjacent: Neighbors extends true ? Adjacent<{
-    id: string;
-  }> : Adjacent<RelationalQueryResult<Registry, Name, Neighbors>>;
+  _adjacent: Adjacent<RelationalQueryResult<Registry, Name, Neighbors>>;
 } : {};
 type Simplify<Value> = { [Key in keyof Value]: Value[Key]; };
 type RequestedPayloads<Payloads, Requested> = { -readonly [Key in keyof Requested as Requested[Key] extends false | undefined ? never : Key]-?: Key extends keyof Payloads ? Payloads[Key] : never; };
@@ -259,20 +435,35 @@ type PayloadResult<Registry extends CollectionRegistry, Name extends keyof Regis
 } ? keyof RequestedPayloads<PayloadsOf<Registry[Name]>, Requested> extends never ? {} : {
   _payloads: Simplify<RequestedPayloads<PayloadsOf<Registry[Name]>, Requested>>;
 } : {};
-/** Infers selected columns and relationships, preserving optional metadata in default projections. */
+/** Infers exactly the selected columns, relationships, adjacency, and payloads. */
 type RelationalQueryResult<Registry extends CollectionRegistry, Name extends keyof Registry & string, Options> = Options extends unknown ? Simplify<ColumnResult<QueryData<Registry[Name]>, Options> & IncludedResult<Registry, Name, Options> & AdjacentResult<Registry, Name, Options> & PayloadResult<Registry, Name, Options>> : never;
 type CheckedConditions<Value, Filters extends readonly unknown[]> = { [Index in keyof Filters]: CheckedCondition<Value, Filters[Index]>; };
 type CheckedCondition<Value, Filter> = Filter extends Scalar ? Filter : { [Key in keyof Filter]: Key extends "AND" | "OR" ? Filter[Key] extends readonly unknown[] ? CheckedConditions<Value, Filter[Key]> : never : Key extends "NOT" ? CheckedCondition<Value, Filter[Key]> : Key extends keyof FieldFilter<Value> ? Filter[Key] : never; };
 type CheckedWhereList<Registry extends CollectionRegistry, Name extends keyof Registry & string, Filters extends readonly unknown[]> = { [Index in keyof Filters]: CheckedWhere<Registry, Name, Filters[Index]>; };
-type CheckedWhere<Registry extends CollectionRegistry, Name extends keyof Registry & string, Filter> = { [Key in keyof Filter]: Key extends "AND" | "OR" | "NOT" ? Filter[Key] extends readonly unknown[] ? CheckedWhereList<Registry, Name, Filter[Key]> : CheckedWhere<Registry, Name, Filter[Key]> : Key extends "RAW" ? Filter[Key] : Key extends keyof RelationshipsOf<Registry[Name]> ? Filter[Key] extends boolean ? Filter[Key] : CheckedWhere<Registry, RelatedName<Registry, Name, Key>, Filter[Key]> : Key extends keyof QueryData<Registry[Name]> ? CheckedCondition<QueryData<Registry[Name]>[Key], Filter[Key]> : never; };
+type CheckedWhere<Registry extends CollectionRegistry, Name extends keyof Registry & string, Filter> = { [Key in keyof Filter]: Key extends "AND" | "OR" | "NOT" ? Filter[Key] extends readonly unknown[] ? CheckedWhereList<Registry, Name, Filter[Key]> : CheckedWhere<Registry, Name, Filter[Key]> : Key extends "RAW" ? Filter[Key] : Key extends keyof RelationshipsOf<Registry[Name]> ? Filter[Key] extends boolean ? Filter[Key] : CheckedWhere<Registry, RelatedName<Registry, Name, Key>, Filter[Key]> : Key extends keyof QueryData<Registry[Name]> ? CheckedCondition<QueryData<Registry[Name]>[Key], Filter[Key]> : UnavailableRelationship<Registry[Name], Key>; };
 /** Rejects unknown options recursively, including options supplied through inferred variables. */
-type CheckedRelationalOptions<Registry extends CollectionRegistry, Name extends keyof Registry & string, Options, Many extends boolean = true, AllowAdjacent extends boolean = true, Pagination extends boolean = true> = { [Key in keyof Options]: Key extends "columns" ? { [Column in keyof Options[Key]]: Column extends keyof QueryData<Registry[Name]> ? Options[Key][Column] : never; } : Key extends "where" ? CheckedWhere<Registry, Name, Options[Key]> : Key extends "with" ? { [Related in keyof Options[Key]]: Related extends keyof RelationshipsOf<Registry[Name]> ? Options[Key][Related] extends boolean ? Options[Key][Related] : CheckedRelationalOptions<Registry, RelatedName<Registry, Name, Related>, Options[Key][Related], IsMany<Registry, Name, Related>, AllowAdjacent> : never; } : Key extends "adjacent" ? AllowAdjacent extends true ? Options[Key] extends true ? true : CheckedRelationalOptions<Registry, Name, Options[Key], true, false, false> : never : Key extends "payloads" ? AllowAdjacent extends true ? { [Payload in keyof Options[Key]]: Payload extends keyof PayloadsOf<Registry[Name]> ? Options[Key][Payload] : never; } : never : Key extends "orderBy" ? Key extends keyof RelationalQueryOptions<Registry, Name, Many, AllowAdjacent, Pagination> ? { [Field in keyof Options[Key]]: Field extends keyof OrderBy<QueryData<Registry[Name]>> ? Options[Key][Field] : never; } : never : Key extends keyof RelationalQueryOptions<Registry, Name, Many, AllowAdjacent, Pagination> ? Options[Key] : never; };
+type CheckedRelationalOptions<Registry extends CollectionRegistry, Name extends keyof Registry & string, Options, Many extends boolean = true, AllowAdjacent extends boolean = true, Pagination extends boolean = true> = { [Key in keyof Options]: Key extends "columns" ? { [Column in keyof Options[Key]]: Column extends keyof QueryData<Registry[Name]> ? Options[Key][Column] : never; } : Key extends "where" ? CheckedWhere<Registry, Name, Options[Key]> : Key extends "with" ? { [Related in keyof Options[Key]]: Related extends keyof RelationshipsOf<Registry[Name]> ? Options[Key][Related] extends false | undefined ? Options[Key][Related] : CheckedRelationalOptions<Registry, RelatedName<Registry, Name, Related>, Options[Key][Related], IsMany<Registry, Name, Related>, AllowAdjacent> & SelectionRequired<Options[Key][Related]> : UnavailableRelationship<Registry[Name], Related>; } : Key extends "adjacent" ? AllowAdjacent extends true ? CheckedRelationalOptions<Registry, Name, Omit<Options[Key], "scope">, true, false, false> & SelectionRequired<Options[Key]> & (Options[Key] extends {
+  scope: "results";
+} ? {
+  scope: "results";
+  where?: never;
+  orderBy?: never;
+} : {
+  scope?: "collection";
+}) : never : Key extends "payloads" ? AllowAdjacent extends true ? { [Payload in keyof Options[Key]]: Payload extends keyof PayloadsOf<Registry[Name]> ? CheckedPayloadRequest<Options[Key][Payload], VariantOf<Registry[Name], Payload>> : never; } : never : Key extends "orderBy" ? Key extends keyof RelationalQueryOptions<Registry, Name, Many, AllowAdjacent, Pagination> ? { [Field in keyof Options[Key]]: Field extends keyof OrderBy<QueryData<Registry[Name]>> ? Options[Key][Field] : never; } : never : Key extends keyof RelationalQueryOptions<Registry, Name, Many, AllowAdjacent, Pagination> ? Options[Key] : never; };
+/** One collection's relational queries: `findMany`, `findFirst`, and `paginate`. */
+type RelationalCollectionQueries<Registry extends CollectionRegistry, Name extends keyof Registry & string> = {
+  /** Returns matching rows with exactly the selected data. Options must select something. */
+  findMany<const Options extends RelationalQueryOptions<Registry, Name>>(options: Options & CheckedRelationalOptions<Registry, Name, NoInfer<Options>> & SelectionRequired<NoInfer<Options>>): Promise<RelationalQueryResult<Registry, Name, Options>[]>;
+  /** Returns the first matching row, or undefined when none matches. */
+  findFirst<const Options extends RelationalQueryOptions<Registry, Name>>(options: Options & CheckedRelationalOptions<Registry, Name, NoInfer<Options>> & SelectionRequired<NoInfer<Options>>): Promise<RelationalQueryResult<Registry, Name, Options> | undefined>;
+  /**
+   * Returns one page from one revision: `page` and `size` for page numbers, or `size` with
+   * `after`, `before`, or `total` for cursors. `limit` and `offset` are unavailable.
+   */
+  paginate<const Options extends RelationalPaginateOptions<Registry, Name>>(options: Options & CheckedRelationalOptions<Registry, Name, NoInfer<Omit<Options, PaginateKey>>, true, true, false> & SelectionRequired<NoInfer<Options>>): Promise<PaginateResult<RelationalQueryResult<Registry, Name, Options>, Options>>;
+};
 /** Typed per-collection query entry points that never expose source configuration at runtime. */
-type RelationalQueries<Registry extends CollectionRegistry> = string extends keyof Registry ? {} : { readonly [Name in keyof Registry & string]: {
-  /** Returns matching metadata rows and requested relationships. */
-  findMany<const Options extends RelationalQueryOptions<Registry, Name> = {}>(options?: Options & CheckedRelationalOptions<Registry, Name, NoInfer<Options>>): Promise<RelationalQueryResult<Registry, Name, Options>[]>;
-  /** Returns the first matching entry, or undefined when none matches. */
-  findFirst<const Options extends RelationalQueryOptions<Registry, Name> = {}>(options?: Options & CheckedRelationalOptions<Registry, Name, NoInfer<Options>>): Promise<RelationalQueryResult<Registry, Name, Options> | undefined>;
-}; };
+type RelationalQueries<Registry extends CollectionRegistry> = string extends keyof Registry ? {} : { readonly [Name in keyof Registry & string]: RelationalCollectionQueries<Registry, Name>; };
 //#endregion
-export { QueryPlan as _, RelationalWhere as a, Fields as c, Scalar as d, ScalarField as f, Expression as g, Where as h, RelationalQueryResult as i, Ordered as l, SelectionResult as m, RelationalQueries as n, Adjacent as o, Selection as p, RelationalQueryOptions as r, Field$1 as s, RelationalCountOptions as t, Query as u, QueryRegistry as v };
+export { Selection as C, QueryPlan as D, Expression as E, QueryRegistry as O, ScalarField as S, Where as T, PaginateResult as _, RelationalQueryOptions as a, RelationField as b, Adjacent as c, Field$1 as d, Fields as f, PaginateOptions as g, PageOptions as h, RelationalQueries as i, QueryTerminal as k, CursorOptions as l, Ordered as m, RelationalCountOptions as n, RelationalQueryResult as o, NumberedPage as p, RelationalPaginateOptions as r, RelationalWhere as s, RelationalCollectionQueries as t, CursorPage as u, Query as v, SelectionResult as w, Scalar as x, QueryFields as y };

package/dist/revision-DBwU-aC9.d.mts

@@ -0,0 +1,56 @@
+import { s as ContentError } from "./collection-types-CsQtGw7_.mjs";
+import { n as ContentRenderResult } from "./types-Dh-Sydyw.mjs";
+import { _ as Relationship } from "./types-Dz1vTXa2.mjs";
+import { D as QueryPlan, O as QueryRegistry, k as QueryTerminal } from "./relational-types-CTcalUNW.mjs";
+import { n as QueryStyle } from "./query-style-C2FcT1f9.mjs";
+//#region src/runtime/revision.d.ts
+type QueryRecord = Record<string, unknown> & {
+  id: string;
+};
+/** Custom payload loaders by payload name, entry ID, and canonical variant key. */
+type CustomPayloadTable = ReadonlyMap<string, ReadonlyMap<string, ReadonlyMap<string, () => Promise<unknown>>>>;
+/** The built-in side payload shared by an entry's `_body` and `_rendered` payloads. */
+type BuiltinPayload = {
+  body?: string;
+  rendered?: ContentRenderResult;
+  markdown?: string;
+};
+type PreparedCollection = {
+  records: readonly QueryRecord[];
+  relationships: Record<string, Relationship>;
+  /** Lazy built-in payloads, present only for entries with a body or rendered output. */
+  builtins: ReadonlyMap<string, () => Promise<BuiltinPayload>>;
+  /**
+   * Lazy custom payloads by payload name, entry ID, and canonical variant key. A missing variant
+   * key means the entry has no such combination.
+   */
+  payloads?: CustomPayloadTable;
+  sources?: ReadonlyMap<string, string | undefined>;
+};
+type PreparedRevision = {
+  registry: QueryRegistry;
+  collections: Record<string, PreparedCollection>;
+  relations: Map<string, Map<string, readonly QueryRecord[]>>;
+  active: number;
+  /** Built-in payloads keyed by collection and ID; custom payloads also by name and variant. */
+  payloadCache: Map<string, Promise<unknown>>;
+  renderCache: Map<string, Promise<ContentRenderResult>>;
+  renderMarkdown?: (body: string) => Promise<ContentRenderResult>;
+  /** The only query style this revision's configuration allows; absent allows both. */
+  queryStyle?: QueryStyle;
+  execute?: (plan: QueryPlan, terminal: QueryTerminal, requests: PayloadRequest[]) => Promise<unknown>;
+};
+/** A projected row awaiting the payloads its query scope requested. */
+type PayloadRequest = {
+  target: Record<string, unknown>;
+  collection: string;
+  id: string;
+  payloads: NonNullable<QueryPlan["payloads"]>;
+};
+type ContentState = {
+  revision?: PreparedRevision;
+  registry?: QueryRegistry;
+  error?: ContentError;
+};
+//#endregion
+export { PreparedRevision as n, ContentState as t };

package/dist/runtime.d.mts

@@ -1,3 +1,4 @@
-import { a as ContentDiagnostic, o as ContentError, s as ContentErrorCode, t as Content } from "./content-lwPxE9Yu.mjs";
+import { c as ContentErrorCode, i as LoadedRegistry, n as Collection, o as ContentDiagnostic, r as CollectionHandles, s as ContentError, t as AnyCollection } from "./collection-types-CsQtGw7_.mjs";
 import { n as ContentRenderResult, t as ContentHeading } from "./types-Dh-Sydyw.mjs";
-export { type Content, type ContentDiagnostic, ContentError, type ContentErrorCode, type ContentHeading, type ContentRenderResult };
+import { n as QueryStyle, r as QueryStyleDisabled } from "./query-style-C2FcT1f9.mjs";
+export { type AnyCollection, type Collection, type CollectionHandles, type ContentDiagnostic, ContentError, type ContentErrorCode, type ContentHeading, type ContentRenderResult, type LoadedRegistry, type QueryStyle, type QueryStyleDisabled };

package/dist/runtime.mjs

@@ -1,5 +1,5 @@
 //#endregion
-export { t as ContentError } from "./errors-C2iuBM0G.mjs";
+export { t as ContentError } from "./errors-Bfd0R4_P.mjs";
 import { t as assertServerOnly } from "./server-only-CIJUlyL-.mjs";
 //#region src/runtime.ts
 assertServerOnly();