content-query 0.2.0 → 0.4.0

package/dist/{relational-types-DgK3rLuw.d.mts → relational-types-C8xJtLG5.d.mts}

@@ -1,4 +1,4 @@
-import { c as Relationship, i as CollectionRegistry, l as RelationshipsOf, o as PayloadsOf, s as QueryData } from "./types-C-kdMblM.mjs";
+import { S as VariantOf, _ as RelationshipsOf, g as Relationship, h as QueryData, i as CollectionRegistry, m as PayloadsOf } from "./types-DbFfF6JE.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,10 +34,19 @@ 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>>;
 };
+/**
+ * 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>>;
@@ -46,15 +60,29 @@ type QueryRegistry = Record<string, {
   /** Payload names available to queries; omitted when the collection has none. */
   payloads?: Record<string, PayloadDescriptor>;
 }>;
+/** 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.";
 //#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>>>>; };
 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;
@@ -82,7 +110,7 @@ type RelationshipResult<Definition, Relation extends Relationship, Result, Filte
 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>;
+  where(configure: (fields: QueryFields<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>;
 } & (Many extends true ? {
   orderBy(field: SortKey<QueryData<Registry[Name]>>, direction?: "asc" | "desc"): Query<Registry, Name, Result, Selected, Many, Root, Filtered, AllowAdjacent, Pagination>;
@@ -91,11 +119,10 @@ type Query<Registry extends CollectionRegistry, Name extends keyof Registry & st
   offset(value: number): Query<Registry, Name, Result, Selected, Many, Root, Filtered, AllowAdjacent, Pagination>;
 } : {} : {}) & (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;
-    }>;
+  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>;
+  /** 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>;
   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>>;
@@ -104,11 +131,11 @@ type Query<Registry extends CollectionRegistry, Name extends keyof Registry & st
     _adjacent: Adjacent<SelectionResult<Registry, Name, Options["select"]>>;
   }, true, Many, Root, Filtered, AllowAdjacent, Pagination>;
 } : {}) & (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>;
@@ -149,7 +176,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 +187,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 +255,69 @@ 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 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 +326,28 @@ 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; };
 /** 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]> : never; } : 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; };
 /** 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>;
+  /** 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>;
 }; };
 //#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 { Where as _, RelationalWhere as a, QueryRegistry as b, Fields as c, QueryFields as d, RelationField as f, SelectionResult as g, Selection as h, RelationalQueryResult as i, Ordered as l, ScalarField as m, RelationalQueries as n, Adjacent as o, Scalar as p, RelationalQueryOptions as r, Field$1 as s, RelationalCountOptions as t, Query as u, Expression as v, QueryPlan as y };

package/dist/runtime.d.mts

@@ -1,3 +1,4 @@
+import { a as ContentDiagnostic, o as ContentError, s as ContentErrorCode, t as Content } from "./content-CwTKqRs9.mjs";
 import { n as ContentRenderResult, t as ContentHeading } from "./types-Dh-Sydyw.mjs";
-import { a as ContentError, i as ContentDiagnostic, o as ContentErrorCode, t as Content } from "./content-G69dPPuo.mjs";
-export { type Content, type ContentDiagnostic, ContentError, type ContentErrorCode, type ContentHeading, type ContentRenderResult };
+import { n as QueryStyle, r as QueryStyleDisabled } from "./query-style-eXENQJ0O.mjs";
+export { type Content, type ContentDiagnostic, ContentError, type ContentErrorCode, type ContentHeading, type ContentRenderResult, 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();

package/dist/types-DbFfF6JE.d.mts

@@ -0,0 +1,181 @@
+import { c as Loader, n as GlobOptions, t as FileOptions } from "./descriptor-bcPa6XLk.mjs";
+import { n as ContentRenderResult, r as RenderedContent } from "./types-Dh-Sydyw.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/collection/types.d.ts
+declare const builtinPayloadsType: unique symbol;
+declare const customPayloadsType: unique symbol;
+type Schema = StandardSchemaV1;
+type SchemaOutput<Value> = Value extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Value> : Record<string, unknown>;
+/** One file or record that a `files` helper read, shaped like a loader entry. */
+type FileEntry<Data = Record<string, unknown>> = {
+  id: string;
+  data: Data;
+  /** The Markdown body, when the file is Markdown and `retainBody` is not `false`. */
+  body?: string;
+  /** The file's path relative to the project root. */
+  filePath: string;
+};
+/**
+ * Tracked file access for computed and payload resolvers. Paths are relative to the entry's
+ * folder and must stay inside it or one of the collection's `sharedFiles` directories. Every read
+ * is recorded, so editing, adding, or removing a file re-resolves only what read it.
+ */
+type EntryFiles = {
+  /** Lists and parses files like `glob()`, with `base` relative to the entry's folder. */
+  glob<FileSchema extends Schema | undefined = undefined>(options: Omit<GlobOptions, "base" | "deferRender"> & {
+    base?: string;
+    schema?: FileSchema;
+  }): Promise<FileEntry<SchemaOutput<FileSchema>>[]>;
+  /** Parses one data file's records like `file()`, returning one entry per record. */
+  file<FileSchema extends Schema | undefined = undefined>(filePath: string, options?: FileOptions & {
+    schema?: FileSchema;
+  }): Promise<FileEntry<SchemaOutput<FileSchema>>[]>;
+  /** Reads a file as UTF-8 text. */
+  text(filePath: string): Promise<string>;
+  /** Reads a file's bytes. */
+  bytes(filePath: string): Promise<Uint8Array>;
+  /** Renders Markdown with the built-in renderer, like a loader's `renderMarkdown()`. */
+  renderMarkdown(body: string): Promise<RenderedContent>;
+};
+type ComputedContext<Data, Source = unknown> = {
+  /** The collection's key in the configured registry. */
+  collection: string;
+  id: string;
+  /** Loader-provided source metadata, detached from stored entries for this resolver. */
+  source?: Source extends object ? Readonly<Source> : Source;
+  data: Readonly<Data>;
+  readBody(this: void): Promise<string | undefined>;
+  /** Tracked reads of files beside the entry; edits re-prepare the entry. */
+  files: EntryFiles;
+  signal: AbortSignal;
+};
+type ComputedDefinition<Data = Record<string, unknown>, Source = unknown> = {
+  schema: Schema;
+  resolve(context: ComputedContext<Data, Source>): unknown;
+};
+/** Context for a payload's `combinations()` override, with the entry's prepared data. */
+type VariantContext<Data, Source = unknown> = {
+  /** The collection's key in the configured registry. */
+  collection: string;
+  id: string;
+  /** Loader-provided source metadata, detached from stored entries for this resolver. */
+  source?: Source extends object ? Readonly<Source> : Source;
+  /** Validated metadata plus computed fields. */
+  data: Readonly<Data>;
+  signal: AbortSignal;
+};
+/** Context for a custom payload resolver, called once per entry and variant combination. */
+type PayloadContext<Data, Source = unknown, Variant = {}> = VariantContext<Data, Source> & {
+  /** The variant combination being resolved; empty for payloads without variants. */
+  variant: Readonly<Variant>;
+  readBody(this: void): Promise<string | undefined>;
+  /** Tracked reads of files beside the entry; edits re-resolve only this variant. */
+  files: EntryFiles;
+};
+/** Data fields, including computed fields, whose values are string arrays. */
+type VariantField<Data> = { [Field in keyof Data]-?: NonNullable<Data[Field]> extends readonly string[] ? Field : never; }[keyof Data] & string;
+/**
+ * Enumerates one variant key's values: the name of a string-array data field, read per entry, or
+ * a fixed list. Derive values in a computed field when they need logic.
+ */
+type VariantValues<Data> = VariantField<Data> | readonly string[];
+/**
+ * A custom payload: schema-validated data resolved during preparation and loaded only when a
+ * query requests it. Names cannot start with `_`, which built-in payloads such as `_body` use.
+ */
+type PayloadDefinition<Data = Record<string, unknown>, Source = unknown, Variant = {}> = {
+  schema: Schema;
+  /** Variant keys and their values for an entry. Omit for a single payload value. */
+  variants?: Record<string, VariantValues<Data>>;
+  /**
+   * Overrides the default cross product of enumerated values. Each combination must name every
+   * variant key with one of that key's enumerated values.
+   */
+  combinations?(context: VariantContext<Data, Source> & {
+    variants: Readonly<Record<string, readonly string[]>>;
+  }): Iterable<Variant> | PromiseLike<Iterable<Variant>>;
+  resolve(context: PayloadContext<Data, Source, Variant>): unknown;
+  /**
+   * Set to `false` to resolve again in every revision, for resolvers that read data `files` cannot
+   * track, such as a remote API. Defaults to `true`.
+   */
+  cache?: boolean;
+};
+/**
+ * Any payload declaration once its inferred types are erased, as registries and preparation see
+ * it. Typed declarations from `defineCollection` are always assignable.
+ */
+type PayloadDeclaration = {
+  schema: Schema;
+  variants?: Record<string, string | readonly string[]>;
+  combinations?(context: never): unknown;
+  resolve(context: never): unknown;
+  cache?: boolean;
+};
+type Relationship = {
+  collection: string;
+  type: "one" | "many";
+  from: string;
+  to: string;
+  referenceSide: "from" | "to" | "none";
+};
+type CollectionDefinition<SourceSchema extends Schema | undefined = Schema | undefined, Computed extends Record<string, ComputedDefinition<never, never>> = Record<string, ComputedDefinition<never, never>>, Relationships extends Record<string, Relationship> = Record<string, Relationship>> = {
+  loader: Loader;
+  schema?: SourceSchema;
+  computed?: Computed;
+  relationships?: Relationships;
+  payloads?: Record<string, PayloadDeclaration>;
+  /** Directories, relative to the project root, that every entry's `files` helpers may read. */
+  sharedFiles?: readonly string[];
+};
+type CollectionRegistry = Record<string, CollectionDefinition>;
+type EntryData<Definition> = Definition extends {
+  schema: infer SourceSchema;
+} ? SchemaOutput<SourceSchema> : Record<string, unknown>;
+type ComputedData<Definition> = Definition extends {
+  computed: infer Computed;
+} ? { [Name in keyof Computed]: Computed[Name] extends {
+  schema: infer ResultSchema;
+} ? SchemaOutput<ResultSchema> : never; } : {};
+type QueryData<Definition> = {
+  id: string;
+} & EntryData<Definition> & ComputedData<Definition>;
+type RelationshipsOf<Definition> = Definition extends {
+  relationships: infer Relationships;
+} ? Relationships : {};
+/**
+ * Payloads that Markdown sources, `glob()`, and custom loaders provide for every entry.
+ * Built-in names start with an underscore, so they never collide with custom payloads.
+ */
+type BuiltinPayloads = {
+  /** The retained raw body, or undefined when the entry has none or retention is disabled. */
+  _body: string | undefined;
+  /** HTML and headings; entries without a rendering path reject with `not-renderable`. */
+  _rendered: ContentRenderResult;
+};
+/** Type-only marker recording which built-in payloads a defined collection carries. */
+type BuiltinPayloadMarker<Available extends keyof BuiltinPayloads> = {
+  readonly [builtinPayloadsType]?: Available;
+};
+/** One custom payload's validated value type and variant record, as recorded by a definition. */
+type CustomPayload<Value = unknown, Variant = {}> = {
+  value: Value;
+  variant: Variant;
+};
+/** Type-only marker recording a defined collection's custom payload values and variant keys. */
+type CustomPayloadMarker<Payloads extends Record<string, CustomPayload>> = {
+  readonly [customPayloadsType]?: Payloads;
+};
+type CustomPayloadsOf<Definition> = Definition extends {
+  readonly [customPayloadsType]?: infer Payloads;
+} ? Payloads extends Record<string, CustomPayload> ? Payloads : {} : {};
+/** Payload names and value types that queries can request for a collection definition. */
+type PayloadsOf<Definition> = (Definition extends {
+  readonly [builtinPayloadsType]?: infer Available;
+} ? Pick<BuiltinPayloads, Available & keyof BuiltinPayloads> : BuiltinPayloads) & { [Name in keyof CustomPayloadsOf<Definition>]: CustomPayloadsOf<Definition>[Name] extends CustomPayload<infer Value> ? Value : never; };
+/** The value type of one payload that queries return under `_payloads`. */
+type PayloadData<Definition, Name extends keyof PayloadsOf<Definition>> = PayloadsOf<Definition>[Name];
+/** The variant keys a payload request must supply; empty for built-in and single-value payloads. */
+type VariantOf<Definition, Name> = Name extends keyof CustomPayloadsOf<Definition> ? CustomPayloadsOf<Definition>[Name] extends CustomPayload<unknown, infer Variant> ? Variant : {} : {};
+//#endregion
+export { VariantValues as C, VariantOf as S, RelationshipsOf as _, ComputedContext as a, VariantContext as b, EntryFiles as c, PayloadData as d, PayloadDeclaration as f, Relationship as g, QueryData as h, CollectionRegistry as i, FileEntry as l, PayloadsOf as m, BuiltinPayloads as n, CustomPayload as o, PayloadDefinition as p, CollectionDefinition as r, CustomPayloadMarker as s, BuiltinPayloadMarker as t, PayloadContext as u, Schema as v, VariantField as x, SchemaOutput as y };

package/dist/vite.d.mts

@@ -1,6 +1,18 @@
-import { t as BuildContentOptions } from "./build-DfKd2bpf.mjs";
+import { a as ContentSourceEvent, o as ContentSourceSnapshot, t as BuildContentOptions } from "./build-DL1GzmRy.mjs";
 import { Plugin } from "vite";
 //#region src/integrations/vite/plugin.d.ts
+/** Public, format-neutral hooks for integrations sharing this plugin's preparation session. */
+type ContentQueryPluginApi = {
+  /** Prepares or awaits the shared session and returns its current source identities. */
+  prepare(): Promise<ContentSourceSnapshot>;
+  /** Observes subsequent source publications and errors without owning another watcher. */
+  subscribe(listener: (event: ContentSourceEvent) => void): () => void;
+};
+/** A normal Vite plugin with a typed source-integration API. */
+interface ContentQueryPlugin extends Plugin<ContentQueryPluginApi> {
+  api: ContentQueryPluginApi;
+}
 /** Integrates in-memory content with Vite; opt into generated storage for standalone artifacts. */
-export declare function contentQuery(options?: Omit<BuildContentOptions, "watch">): Plugin;
-//#endregion
+export declare function contentQuery(options?: Omit<BuildContentOptions, "watch">): ContentQueryPlugin;
+//#endregion
+export type { ContentQueryPlugin, ContentQueryPluginApi };

package/dist/vite.mjs

@@ -1,5 +1,5 @@
-import { a as sessionInternals, i as resolveConfigPath, l as virtualDeclarations, o as withinDirectory, r as configCandidates, s as writeChanged, t as buildAtRoot, u as revisionModules } from "./build-Dxz7P1ur.mjs";
-import { n as serializeContentError } from "./diagnostics-Cu94mZhl.mjs";
+import { a as sessionInternals, i as resolveConfigPath, l as virtualDeclarations, o as withinDirectory, r as configCandidates, s as writeChanged, t as buildAtRoot, u as revisionModules } from "./build-CcqIpkes.mjs";
+import { n as serializeContentError } from "./diagnostics-DmUZtrJ6.mjs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
@@ -122,6 +122,7 @@ function contentQuery(options = {}) {
 	let encoding;
 	const bridgeKey = randomUUID();
 	const refreshClients = /* @__PURE__ */ new WeakSet();
+	const sourceListeners = /* @__PURE__ */ new Set();
 	/** Publishes type-only facade binding without importing configuration in executable code. */
 	async function writeTypes(configPath) {
 		const directory = path.join(config.root, ".content-query");
@@ -216,6 +217,14 @@ function contentQuery(options = {}) {
 				if (config.command === "serve") changed(state).catch(deliveryFailed);
 			});
 			session = prepared;
+			prepared.subscribe((event) => {
+				const listeners = [...sourceListeners];
+				for (const listener of listeners) try {
+					listener(event);
+				} catch (cause) {
+					config.logger.error(`Content source subscriber failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+				}
+			});
 			try {
 				if (config.command === "serve") {
 					const global = globalThis;
@@ -235,6 +244,19 @@ function contentQuery(options = {}) {
 	}
 	return {
 		name: "content-query",
+		api: {
+			async prepare() {
+				const prepared = await ensureSession();
+				await sessionInternals(prepared).idle();
+				return prepared.sources();
+			},
+			subscribe(listener) {
+				sourceListeners.add(listener);
+				return () => {
+					sourceListeners.delete(listener);
+				};
+			}
+		},
 		enforce: "pre",
 		configResolved(resolved) {
 			config = resolved;
@@ -288,6 +310,7 @@ function contentQuery(options = {}) {
 			server = void 0;
 			await starting?.catch(() => void 0);
 			await session?.dispose();
+			sourceListeners.clear();
 			globalThis[bridgeSymbol]?.delete(bridgeKey);
 		}
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "content-query",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Typed, framework-independent content collections, queries, and rendering.",
   "homepage": "https://github.com/yangshun/content-query#readme",
   "bugs": {
@@ -71,7 +71,7 @@
     "vite-plus": "1.3.0"
   },
   "peerDependencies": {
-    "next": "^16.0.0",
+    "next": "^15.0.0 || ^16.0.0",
     "vite": "^8.0.0"
   },
   "peerDependenciesMeta": {

package/dist/build-DfKd2bpf.d.mts

@@ -1,25 +0,0 @@
-import { i as CollectionRegistry } from "./types-C-kdMblM.mjs";
-import { s as InvalidRelationships, t as Content } from "./content-G69dPPuo.mjs";
-//#region src/preparation/session.d.ts
-type ContentSession<Registry extends CollectionRegistry = {}> = {
-  content: Content<Registry>;
-  dispose(): Promise<void>;
-};
-//#endregion
-//#region src/preparation/build.d.ts
-/** Options shared by standalone content builds and host integrations. */
-type BuildContentOptions = {
-  /** Exact config path; omission discovers one content-query.config.{ts,mts,cts,js,mjs,cjs} file. */
-  config?: string;
-  backend?: "in-memory" | "generated";
-  /** Generated backend output directory, relative to the application root; defaults to ./.content-query. */
-  outDir?: string;
-  watch?: boolean;
-};
-/**
- * Builds content independently of a bundler; bind the registry through an erased type import.
- * Generated watch sessions prune previous-run artifacts after their first successful publication.
- */
-declare function buildContent<Registry extends CollectionRegistry = {}>(...arguments_: InvalidRelationships<Registry> extends never ? [options?: BuildContentOptions] : [invalidRegistry: never]): Promise<ContentSession<Registry>>;
-//#endregion
-export { buildContent as n, ContentSession as r, BuildContentOptions as t };