content-query 0.3.0 → 0.4.0

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,4 +1,4 @@
-import { a as ContentSourceEvent, o as ContentSourceSnapshot, t as BuildContentOptions } from "./build-jKnjDjQE.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. */

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-CI4s0oFP.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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "content-query",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Typed, framework-independent content collections, queries, and rendering.",
   "homepage": "https://github.com/yangshun/content-query#readme",
   "bugs": {

package/dist/descriptor-BUPT2J7X.d.mts

@@ -1,18 +0,0 @@
-import { m as MaybePromise } from "./types-FmUJ3cH1.mjs";
-//#region src/loaders/descriptor.d.ts
-type GlobOptions = {
-  pattern: string | string[];
-  base?: string | URL;
-  generateId?: (context: {
-    entry: string;
-    base: URL;
-    data: Record<string, unknown>;
-  }) => string;
-  retainBody?: boolean;
-  deferRender?: boolean;
-};
-type FileOptions = {
-  parser?: (text: string) => MaybePromise<unknown>;
-};
-//#endregion
-export { GlobOptions as n, FileOptions as t };

package/dist/types-BC8gVJ6u.d.mts

@@ -1,69 +0,0 @@
-import { o as Loader } from "./types-FmUJ3cH1.mjs";
-import { n as ContentRenderResult } from "./types-Dh-Sydyw.mjs";
-import { StandardSchemaV1 } from "@standard-schema/spec";
-//#region src/collection/types.d.ts
-declare const builtinPayloadsType: unique symbol;
-type Schema = StandardSchemaV1;
-type SchemaOutput<Value> = Value extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Value> : Record<string, unknown>;
-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>;
-  signal: AbortSignal;
-};
-type ComputedDefinition<Data = Record<string, unknown>, Source = unknown> = {
-  schema: Schema;
-  resolve(context: ComputedContext<Data, Source>): unknown;
-};
-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;
-};
-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;
-};
-/** 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;
-//#endregion
-export { ComputedContext as a, Relationship as c, SchemaOutput as d, CollectionRegistry as i, RelationshipsOf as l, BuiltinPayloads as n, PayloadsOf as o, CollectionDefinition as r, QueryData as s, BuiltinPayloadMarker as t, Schema as u };

package/dist/validation-D_XdE1pF.mjs

@@ -1,84 +0,0 @@
-import { n as contentError, t as ContentError } from "./errors-C2iuBM0G.mjs";
-import { i as detach } from "./values-BbTV4QT-.mjs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-//#region src/loaders/descriptor.ts
-const builtinSymbol = Symbol.for("content-query.builtin-loader");
-/** Finds library-owned loader settings without depending on module instance identity. */
-function builtinLoader(loader) {
-	return loader[builtinSymbol];
-}
-/** Resolves a loader's watch root from the application root, including file URLs. */
-function builtinPath(descriptor, root) {
-	if (descriptor.kind === "file") return path.resolve(root, descriptor.filename);
-	return descriptor.options.base instanceof URL ? path.resolve(fileURLToPath(descriptor.options.base)) : path.resolve(root, descriptor.options.base ?? ".");
-}
-//#endregion
-//#region src/preparation/validation.ts
-/** Checks records independently from validation-provider schema introspection. */
-function isRecord(value) {
-	return !!value && typeof value === "object" && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
-}
-/** Validates one result, retaining structured provider issues and their original detail. */
-async function validate(schema, value, context) {
-	if (!schema) return value;
-	try {
-		const result = await schema["~standard"].validate(value);
-		if (result.issues) {
-			const firstPath = result.issues[0]?.path?.map((segment) => typeof segment === "object" ? segment.key : segment);
-			throw new ContentError({
-				...context,
-				code: "validation-error",
-				message: result.issues.map((issue) => issue.message).join("; "),
-				issues: result.issues,
-				path: [...context.path ?? [], ...firstPath ?? []]
-			});
-		}
-		return result.value;
-	} catch (cause) {
-		throw contentError(cause, {
-			...context,
-			code: "validation-error",
-			message: "Schema validation failed."
-		});
-	}
-}
-/** Checks loader transport structure and rejects duplicate snapshot/upsert identities. */
-function normalizeSnapshot(entries, collection) {
-	if (!Array.isArray(entries)) throw new ContentError({
-		code: "source-error",
-		collection,
-		message: "load() must return an array of structured entries."
-	});
-	const snapshot = /* @__PURE__ */ new Map();
-	for (const entry of entries) {
-		if (!entry || typeof entry.id !== "string" || !entry.id || !isRecord(entry.data) || entry.body !== void 0 && typeof entry.body !== "string" || entry.source !== void 0 && typeof entry.source !== "string") throw new ContentError({
-			code: "source-error",
-			collection,
-			id: entry && typeof entry === "object" && typeof entry.id === "string" ? entry.id : void 0,
-			source: entry && typeof entry === "object" && typeof entry.source === "string" ? entry.source : void 0,
-			message: "Invalid structured loader entry."
-		});
-		if (snapshot.has(entry.id)) throw new ContentError({
-			code: "duplicate-id",
-			collection,
-			id: entry.id,
-			source: entry.source,
-			message: `Duplicate entry ID "${entry.id}".`
-		});
-		snapshot.set(entry.id, entry);
-	}
-	return snapshot;
-}
-/** Validates supplied rendering data and normalizes omitted headings. */
-function renderedPayload(entry) {
-	if (entry.rendered === void 0) return;
-	const rendered = entry.rendered;
-	if (!rendered || typeof rendered.html !== "string" || rendered.metadata !== void 0 && (!isRecord(rendered.metadata) || rendered.metadata.headings !== void 0 && (!Array.isArray(rendered.metadata.headings) || rendered.metadata.headings.some((heading) => !heading || !Number.isInteger(heading.depth) || heading.depth < 1 || heading.depth > 6 || typeof heading.slug !== "string" || typeof heading.text !== "string")))) throw new Error("Invalid supplied HTML/headings payload.");
-	return {
-		html: rendered.html,
-		headings: detach(rendered.metadata?.headings ?? [])
-	};
-}
-//#endregion
-export { builtinLoader as a, validate as i, normalizeSnapshot as n, builtinPath as o, renderedPayload as r, builtinSymbol as s, isRecord as t };