content-query 0.4.0 → 0.5.0

package/dist/collection-types-CsQtGw7_.d.mts

@@ -0,0 +1,119 @@
+import { _ as Relationship, g as QueryData, i as CollectionRegistry, u as LoadedMarker, v as RelationshipsOf } from "./types-Dz1vTXa2.mjs";
+import { n as RelationalCountOptions, t as RelationalCollectionQueries, v as Query } from "./relational-types-CTcalUNW.mjs";
+import { i as QueryStyleMember, n as QueryStyle, r as QueryStyleDisabled, t as MembersOf } from "./query-style-C2FcT1f9.mjs";
+//#region src/shared/errors.d.ts
+type ContentErrorCode = "variant-not-found" | "not-renderable" | "source-error" | "validation-error" | "duplicate-id" | "invalid-reference" | "invalid-query" | "invalid-cursor" | "artifact-error" | "render-error";
+type ContentDiagnostic = {
+  code: ContentErrorCode;
+  message: string;
+  operation?: string;
+  collection?: string;
+  id?: string;
+  source?: string;
+  path?: readonly PropertyKey[];
+  /** The custom payload being resolved or loaded. */
+  payload?: string;
+  /** The payload's variant combination, with keys in sorted order. */
+  variant?: Readonly<Record<string, string>>;
+  issues?: readonly unknown[];
+  cause?: unknown;
+};
+/** A contextual library failure; inspect code and diagnostics instead of message text. */
+declare class ContentError extends Error {
+  /** Recognizes contextual errors across preparation and separately bundled loader modules. */
+  static [Symbol.hasInstance](value: unknown): boolean;
+  readonly code: ContentErrorCode;
+  readonly operation?: string;
+  readonly collection?: string;
+  readonly id?: string;
+  readonly source?: string;
+  readonly path?: readonly PropertyKey[];
+  readonly payload?: string;
+  readonly variant?: Readonly<Record<string, string>>;
+  readonly issues?: readonly unknown[];
+  readonly diagnostics: readonly ContentDiagnostic[];
+  /** Creates one failure or a grouped report preserving individual causes and issues. */
+  constructor(options: ContentDiagnostic & {
+    diagnostics?: readonly ContentDiagnostic[];
+  });
+}
+//#endregion
+//#region src/collection/registry-types.d.ts
+type Scalar = string | number | bigint | boolean | Date;
+type Element<Value> = NonNullable<Value> extends readonly (infer Item)[] ? NonNullable<Item> : NonNullable<Value>;
+type Compatible<Left, Right> = NonNullable<Left> extends readonly unknown[] ? NonNullable<Right> extends readonly unknown[] ? false : ScalarCompatible<Left, Right> : ScalarCompatible<Left, Right>;
+type ScalarCompatible<Left, Right> = [Element<Left> | Element<Right>] extends [Scalar] ? [Element<Left>] extends [never] ? true : [Element<Right>] extends [never] ? true : [Extract<Element<Left>, Element<Right>> | Extract<Element<Right>, Element<Left>>] extends [never] ? false : true : false;
+type CheckRelation<Registry extends CollectionRegistry, Name extends keyof Registry, Link extends Relationship> = Link["collection"] extends keyof Registry ? Link["from"] extends keyof QueryData<Registry[Name]> ? Link["to"] extends keyof QueryData<Registry[Link["collection"]]> ? Compatible<QueryData<Registry[Name]>[Link["from"]], QueryData<Registry[Link["collection"]]>[Link["to"]]> extends true ? never : "incompatible-relationship-fields" : "unknown-target-field" : "unknown-source-field" : "unknown-target-collection";
+/** Registry-level relationship checks require the complete inferred collection map. */
+type InvalidRelationships<Registry extends CollectionRegistry> = { [Name in keyof Registry]: { [Link in keyof RelationshipsOf<Registry[Name]>]: RelationshipsOf<Registry[Name]>[Link] extends Relationship ? CheckRelation<Registry, Name, RelationshipsOf<Registry[Name]>[Link]> : "invalid-relationship"; }[keyof RelationshipsOf<Registry[Name]>]; }[keyof Registry];
+//#endregion
+//#region src/runtime/collection-types.d.ts
+declare const collectionType: unique symbol;
+/**
+ * The registry a query scope sees: only the loaded collections, each marked so it offers only the
+ * relationships into loaded collections.
+ */
+type LoadedRegistry<Registry extends CollectionRegistry, Loaded extends keyof Registry & string> = { [Name in Loaded]: Registry[Name] & LoadedMarker<Loaded>; };
+/** The members that start a fluent query; terminals such as `all()` follow one of them. */
+type FluentMember = MembersOf<"fluent">;
+/** The relational members, apart from `count`, which both styles share. */
+type RelationalMember = "findMany" | "findFirst" | "paginate";
+/** Every member before `queryStyle` gating. */
+type CollectionMethods<Registry extends CollectionRegistry, Name extends keyof Registry & string> = Pick<Query<Registry, Name>, FluentMember & keyof Query<Registry, Name>> & RelationalCollectionQueries<Registry, Name>;
+/**
+ * Members outside the allowed style. Calls report the message as the required `this` type,
+ * whatever arguments they pass.
+ */
+type DisabledMembers<Name extends string, Style extends QueryStyle> = { readonly [Member in Exclude<FluentMember | RelationalMember, MembersOf<Style>>]: (this: QueryStyleDisabled<Name, Member & QueryStyleMember, Style>, ...arguments_: readonly unknown[]) => never; };
+/** `count()` counts every entry in both styles; options take relational filters. */
+type CountMember<Registry extends CollectionRegistry, Name extends keyof Registry & string, Style extends QueryStyle> = [Style] extends ["fluent"] ? {
+  /** Counts every entry. Count filtered entries with `where(...).count()`. */
+  count(): Promise<number>;
+} : {
+  /** Counts matching entries before pagination, like the fluent `count()` terminal. */
+  count(options?: RelationalCountOptions<Registry, Name>): Promise<number>;
+};
+/** Reads the collections a collection handle loads. */
+type LoadedOf<Handle> = Handle extends {
+  readonly [collectionType]: {
+    loaded: infer Loaded;
+  };
+} ? Loaded : never;
+/** Any collection handle, as `using()` accepts it. */
+type AnyCollection = {
+  readonly [collectionType]: {
+    loaded: string;
+  };
+};
+/**
+ * One collection's query API, as its generated entry exports it.
+ *
+ * Queries load only this collection and the collections passed to `using()`. Relationships into
+ * any other collection are type errors here and `invalid-query` errors at runtime. `Style` narrows
+ * the members to the `queryStyle` exported by content-query.config; the default allows both.
+ *
+ * @typeParam Registry - The configured collection registry.
+ * @typeParam Name - The queried collection.
+ * @typeParam Style - The allowed query style.
+ * @typeParam Loaded - The collections this handle loads, including `Name`.
+ */
+type Collection<Registry extends CollectionRegistry, Name extends keyof Registry & string, Style extends QueryStyle = QueryStyle, Loaded extends keyof Registry & string = Name> = InvalidRelationships<Registry> extends never ? Pick<CollectionMethods<LoadedRegistry<Registry, Loaded | Name>, Name>, Extract<FluentMember | RelationalMember, MembersOf<Style>>> & DisabledMembers<Name, Style> & CountMember<LoadedRegistry<Registry, Loaded | Name>, Name, Style> & {
+  /**
+   * Supplies other collections, so this collection's queries can follow relationships
+   * into them. Nested relationships need each collection they reach.
+   *
+   * @param collections - Collections imported from their own entries.
+   * @returns A handle over this collection that also loads the supplied collections.
+   */
+  using<const Supplied extends readonly AnyCollection[]>(...collections: Supplied): Collection<Registry, Name, Style, Loaded | (LoadedOf<Supplied[number]> & keyof Registry & string)>;
+  readonly [collectionType]: {
+    readonly name: Name;
+    readonly loaded: Loaded | Name;
+  };
+} : {
+  readonly invalidRelationships: InvalidRelationships<Registry>;
+};
+/** One handle per collection, keyed by collection name, each loading only its own collection. */
+type CollectionHandles<Registry extends CollectionRegistry, Style extends QueryStyle = QueryStyle> = { readonly [Name in keyof Registry & string]: Collection<Registry, Name, Style>; };
+//#endregion
+export { InvalidRelationships as a, ContentErrorCode as c, LoadedRegistry as i, Collection as n, ContentDiagnostic as o, CollectionHandles as r, ContentError as s, AnyCollection as t };

package/dist/computed.d.mts

@@ -1,5 +1,5 @@
 import { g as MaybePromise } from "./descriptor-bcPa6XLk.mjs";
-import { a as ComputedContext } from "./types-DbFfF6JE.mjs";
+import { a as ComputedContext } from "./types-Dz1vTXa2.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/computed/text.d.ts
 /** The syntax removed before computing text-derived fields; literal text preserves all characters. */

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { a as DataStore, c as Loader, d as LoaderLogger, f as LoaderSource, g as MaybePromise, h as RecordLoader, i as DataEntry, l as LoaderConfig, m as MetaStore, n as GlobOptions, o as FileEntrySource, p as LoaderWatcher, r as BodyLoader, s as FileSource, u as LoaderContext } from "./descriptor-bcPa6XLk.mjs";
 import { n as ContentRenderResult, r as RenderedContent, t as ContentHeading } from "./types-Dh-Sydyw.mjs";
-import { C as VariantValues, S as VariantOf, a as ComputedContext, b as VariantContext, c as EntryFiles, d as PayloadData, f as PayloadDeclaration, g as Relationship, h as QueryData, i as CollectionRegistry, l as FileEntry, m as PayloadsOf, n as BuiltinPayloads, o as CustomPayload, p as PayloadDefinition, r as CollectionDefinition, s as CustomPayloadMarker, t as BuiltinPayloadMarker, u as PayloadContext, v as Schema, x as VariantField, y as SchemaOutput } from "./types-DbFfF6JE.mjs";
-import { n as QueryStyle } from "./query-style-eXENQJ0O.mjs";
+import { C as VariantContext, E as VariantValues, T as VariantOf, _ as Relationship, a as ComputedContext, b as SchemaOutput, c as EntryFiles, d as PayloadContext, f as PayloadData, g as QueryData, h as PayloadsOf, i as CollectionRegistry, l as FileEntry, m as PayloadDefinition, n as BuiltinPayloads, o as CustomPayload, p as PayloadDeclaration, r as CollectionDefinition, s as CustomPayloadMarker, t as BuiltinPayloadMarker, w as VariantField, y as Schema } from "./types-Dz1vTXa2.mjs";
+import { n as QueryStyle } from "./query-style-C2FcT1f9.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/collection/source.d.ts
 type CollectionSource = string | ({
@@ -56,6 +56,11 @@ type CollectionFields<SourceSchema extends Schema | undefined, ComputedSchemas e
   }; };
   /** Directories, relative to the project root, that resolvers' `files` helpers may also read. */
   sharedFiles?: readonly string[];
+  /**
+   * The singular name in generated types, such as `"Category"` for `ContentCategory`. Defaults to
+   * the export name without one trailing `s`, so `jobs` generates `ContentJob`.
+   */
+  typeName?: string;
   /** Named per-entry data resolved during preparation and loaded only when a query requests it. */
   payloads?: PayloadDeclarations<SourceSchema, ComputedSchemas, PayloadSchemas, PayloadVariants, Source>;
 };
@@ -83,6 +88,11 @@ declare function collectionOf<SourceSchema extends StandardSchemaV1<unknown, Rec
   source: CollectionSource;
   /** Directories, relative to the project root, that resolvers' `files` helpers may also read. */
   sharedFiles?: readonly string[];
+  /**
+   * The singular name in generated types, such as `"Category"` for `ContentCategory`. Defaults to
+   * the export name without one trailing `s`, so `jobs` generates `ContentJob`.
+   */
+  typeName?: string;
   /** Named per-entry data resolved during preparation and loaded only when a query requests it. */
   payloads?: PayloadDeclarations<SourceSchema, ComputedSchemas, PayloadSchemas, PayloadVariants, FileSource> | undefined;
 } | {
@@ -99,6 +109,11 @@ declare function collectionOf<SourceSchema extends StandardSchemaV1<unknown, Rec
   source?: never;
   /** Directories, relative to the project root, that resolvers' `files` helpers may also read. */
   sharedFiles?: readonly string[];
+  /**
+   * The singular name in generated types, such as `"Category"` for `ContentCategory`. Defaults to
+   * the export name without one trailing `s`, so `jobs` generates `ContentJob`.
+   */
+  typeName?: string;
   /** Named per-entry data resolved during preparation and loaded only when a query requests it. */
   payloads?: PayloadDeclarations<SourceSchema, ComputedSchemas, PayloadSchemas, PayloadVariants, LoaderSource<NoInfer<ContentLoader>>> | undefined;
 };

package/dist/internal.d.mts

@@ -1,8 +1,9 @@
-import { n as createLiveRuntime, o as ContentError, r as PreparedRevision, t as Content } from "./content-CwTKqRs9.mjs";
+import { n as Collection, r as CollectionHandles, s as ContentError } from "./collection-types-CsQtGw7_.mjs";
 import { n as ContentRenderResult } from "./types-Dh-Sydyw.mjs";
-import { i as CollectionRegistry } from "./types-DbFfF6JE.mjs";
-import { b as QueryRegistry } from "./relational-types-C8xJtLG5.mjs";
-import { n as QueryStyle } from "./query-style-eXENQJ0O.mjs";
+import { i as CollectionRegistry } from "./types-Dz1vTXa2.mjs";
+import { O as QueryRegistry } from "./relational-types-CTcalUNW.mjs";
+import { n as QueryStyle } from "./query-style-C2FcT1f9.mjs";
+import { n as PreparedRevision, t as ContentState } from "./revision-DBwU-aC9.mjs";
 //#region src/artifacts/types.d.ts
 type ArtifactManifest = {
   version: number;
@@ -24,10 +25,36 @@ type EncodedCollection = {
 };
 //#endregion
 //#region src/artifacts/runtime.d.ts
-/** Initializes generated/embedded prepared content. This versioned wiring is internal. */
+/**
+ * Initializes generated/embedded prepared content. This versioned wiring is internal.
+ * Relationships are related when a query scope combines the collections it loads.
+ *
+ * @param manifest - The entry's manifest; its registry lists exactly the collections it serves.
+ * @param collections - Generated collection modules by name.
+ * @param renderMarkdown - The packaged renderer, when a served collection captured Markdown.
+ * @returns The prepared revision.
+ */
 export declare function createArtifactRevision(manifest: ArtifactManifest, collections: Record<string, EncodedCollection>, renderMarkdown?: (body: string) => Promise<ContentRenderResult>): PreparedRevision;
-/** Initializes the public generated server export from a complete immutable artifact revision. */
-export declare function createArtifactRuntime<Registry extends CollectionRegistry>(manifest: ArtifactManifest, collections: Record<string, EncodedCollection>, renderMarkdown?: (body: string) => Promise<ContentRenderResult>): Content<Registry, QueryStyle>;
+/**
+ * Initializes one generated collection entry's export.
+ *
+ * @param manifest - The entry's manifest, which lists only this collection.
+ * @param name - The collection's name.
+ * @param collection - The generated collection module.
+ * @param renderMarkdown - The packaged renderer, when the collection captured Markdown.
+ * @returns The collection handle the entry exports.
+ */
+export declare function createArtifactCollection<Registry extends CollectionRegistry, Name extends keyof Registry & string, Style extends QueryStyle = QueryStyle>(manifest: ArtifactManifest, name: Name, collection: EncodedCollection, renderMarkdown?: (body: string) => Promise<ContentRenderResult>): Collection<Registry, Name, Style>;
+/**
+ * Initializes handles for every collection of one artifact revision, sharing its caches. Tests
+ * and integrations use it; applications import each collection's own entry instead.
+ *
+ * @param manifest - A manifest that lists every collection in `collections`.
+ * @param collections - Generated collection modules by name.
+ * @param renderMarkdown - The packaged renderer, when a collection captured Markdown.
+ * @returns Collection handles keyed by collection name.
+ */
+export declare function createArtifactCollections<Registry extends CollectionRegistry, Style extends QueryStyle = QueryStyle>(manifest: ArtifactManifest, collections: Record<string, EncodedCollection>, renderMarkdown?: (body: string) => Promise<ContentRenderResult>): CollectionHandles<Registry, Style>;
 //#endregion
 //#region src/artifacts/payloads.d.ts
 /**
@@ -54,8 +81,21 @@ type PayloadChunk = {
  */
 export declare function createPayloadLoaders(chunks: readonly PayloadChunk[]): EncodedCollection["builtins"];
 //#endregion
+//#region src/runtime/collection.d.ts
+/**
+ * Keeps one collection handle live across host-delivered development revisions.
+ *
+ * @param initial - The first prepared state.
+ * @param name - The collection the handle queries.
+ * @returns The handle and an `update()` that switches its state to a newer revision or error.
+ */
+export declare function createLiveCollection(initial: ContentState, name: string): {
+  collection: object;
+  update(next: ContentState): void;
+};
+//#endregion
 //#region src/runtime/diagnostics.d.ts
 /** Restores the library error and its causes in a generated or isolated development runtime. */
 export declare function restoreContentError(encoded: string): ContentError;
 //#endregion
-export { createLiveRuntime };
+export {};