content-query 0.0.2 → 0.2.0

package/dist/build.d.mts

@@ -0,0 +1,2 @@
+import { n as buildContent, r as ContentSession, t as BuildContentOptions } from "./build-DfKd2bpf.mjs";
+export { type BuildContentOptions, type ContentSession, buildContent };

package/dist/build.mjs

@@ -0,0 +1 @@
+export { n as buildContent } from "./build-Dxz7P1ur.mjs";

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/cli.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { t as ContentError } from "./errors-C2iuBM0G.mjs";
+import { t as buildAtRoot } from "./build-Dxz7P1ur.mjs";
+import { cac } from "cac";
+//#region package.json
+var version = "0.2.0";
+//#endregion
+//#region src/integrations/cli/arguments.ts
+/** Validates one path option after CAC's automatic numeric conversion. */
+function pathOption(value, flag) {
+	if (typeof value !== "string" && typeof value !== "number" || value === "") throw new Error(`Invalid value for ${flag}; expected a path.`);
+	return String(value);
+}
+/** Rejects repeated build options, including aliases that CAC otherwise collapses. */
+function assertSingleOptions(command, arguments_) {
+	const used = /* @__PURE__ */ new Set();
+	for (const argument of arguments_) {
+		const name = argument.split("=", 1)[0];
+		const flags = name.startsWith("--") ? [name.slice(2).replace(/^no-/, "")] : name.startsWith("-") ? name.slice(1).split("") : [];
+		for (const flag of flags) {
+			const option = command.hasOption(flag);
+			if (option) {
+				if (used.has(option.name)) throw new Error(`Repeated option: --${option.name}`);
+				used.add(option.name);
+			}
+		}
+	}
+}
+/** Applies ContentQuery's scalar option and backend contracts to CAC's parsed values. */
+function buildOptions(options) {
+	if (Array.isArray(options["--"]) && options["--"].length > 0) throw new Error("Unexpected arguments after --.");
+	const { config, backend, outDir, watch } = options;
+	if (backend !== void 0 && backend !== "generated" && backend !== "in-memory") throw new Error(`Invalid backend: ${JSON.stringify(backend)}`);
+	if (watch !== void 0 && typeof watch !== "boolean") throw new Error("Invalid value for --watch; expected a boolean.");
+	return {
+		...config === void 0 ? {} : { config: pathOption(config, "--config") },
+		...backend === void 0 ? {} : { backend },
+		...outDir === void 0 ? {} : { outDir: pathOption(outDir, "--out-dir") },
+		...watch === void 0 ? {} : { watch }
+	};
+}
+/** Parses build options with CAC, or prints help/version and returns no build request. */
+function parseArguments(arguments_) {
+	const cli = cac("content-query");
+	let options;
+	const command = cli.command("build", "Build content collections for server-side queries");
+	command.option("-c, --config <file>", "Use an exact configuration file").option("--backend <name>", "Storage backend: generated (default) or in-memory").option("-o, --out-dir <directory>", "Output directory (default: .content-query)").option("-w, --watch", "Watch sources and rebuild after changes").action((parsed) => {
+		assertSingleOptions(command, arguments_);
+		options = buildOptions(parsed);
+	});
+	cli.help().version(version);
+	cli.parse([
+		process.execPath,
+		"content-query",
+		...arguments_
+	], { run: false });
+	if (cli.options.version && cli.matchedCommand) cli.outputVersion();
+	if (cli.options.help || cli.options.version) return;
+	if (!cli.matchedCommand) throw new Error("Usage: content-query build [options]. Run content-query --help for details.");
+	cli.runMatchedCommand();
+	return options;
+}
+//#endregion
+//#region src/integrations/cli/report.ts
+/** Prints structured contextual diagnostics without depending on a framework display. */
+function report(cause) {
+	if (cause instanceof ContentError) for (const diagnostic of cause.diagnostics) console.error(`[content-query:${diagnostic.code}] ${[
+		diagnostic.collection,
+		diagnostic.id,
+		diagnostic.source
+	].filter(Boolean).join(" ")}: ${diagnostic.message}`);
+	else console.error(cause instanceof Error ? cause.message : cause);
+}
+//#endregion
+//#region src/cli.ts
+try {
+	const options = parseArguments(process.argv.slice(2));
+	if (options) {
+		const session = await buildAtRoot(process.cwd(), options, options.watch ? (state) => {
+			if (state.error) report(state.error);
+			else console.log("[content-query] Content ready.");
+		} : void 0);
+		if (options.watch) {
+			process.once("SIGINT", () => {
+				session.dispose();
+			});
+			process.once("SIGTERM", () => {
+				session.dispose();
+			});
+		} else await session.dispose();
+	}
+} catch (cause) {
+	report(cause);
+	process.exitCode = 1;
+}
+//#endregion
+export {};

package/dist/computed.d.mts

@@ -0,0 +1,43 @@
+import { p as MaybePromise } from "./types-ChaNhj42.mjs";
+import { a as ComputedContext } from "./types-C-kdMblM.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. */
+type TextFormat = "markdown" | "text" | "html";
+/** Selects text from validated entry data or loader metadata instead of the captured body. */
+type TextOptions<Data = Record<string, unknown>, Source = unknown> = {
+  /** Defaults to readBody(); undefined text is treated as an empty string. Async selectors are supported. */
+  from?: (context: ComputedContext<Data, Source>) => MaybePromise<string | undefined>;
+  /** Input syntax, defaulting to markdown. */
+  format?: TextFormat;
+};
+/** Controls the reading-speed estimate in addition to selecting its input text. */
+type ReadingTimeOptions<Data = Record<string, unknown>, Source = unknown> = TextOptions<Data, Source> & {
+  /** A finite positive reading speed, defaulting to 200 words per minute. */
+  wordsPerMinute?: number;
+};
+/** Controls the maximum excerpt size in addition to selecting its input text. */
+type ExcerptOptions<Data = Record<string, unknown>, Source = unknown> = TextOptions<Data, Source> & {
+  /** A positive integer, defaulting to 160. Counts graphemes and includes the trailing ellipsis. */
+  maxLength?: number;
+};
+/** Creates a numeric computed field counting normalized text with reading-time's word boundaries. */
+export declare function wordCount<Data = Record<string, unknown>, Source = unknown>(options?: TextOptions<Data, Source>): {
+  schema: StandardSchemaV1<unknown, number>;
+  /** Resolves selected text during preparation and honors cancellation around asynchronous input. */
+  resolve(context: ComputedContext<Data, Source>): Promise<number>;
+};
+/** Creates a numeric computed field estimating whole reading minutes, rounded up; empty text returns zero. */
+export declare function readingTime<Data = Record<string, unknown>, Source = unknown>(options?: ReadingTimeOptions<Data, Source>): {
+  schema: StandardSchemaV1<unknown, number>;
+  /** Resolves selected text during preparation and honors cancellation around asynchronous input. */
+  resolve(context: ComputedContext<Data, Source>): Promise<number>;
+};
+/** Creates a string computed field containing a normalized plain-text excerpt with a bounded length. */
+export declare function excerpt<Data = Record<string, unknown>, Source = unknown>(options?: ExcerptOptions<Data, Source>): {
+  schema: StandardSchemaV1<unknown, string>;
+  /** Resolves selected text during preparation and honors cancellation around asynchronous input. */
+  resolve(context: ComputedContext<Data, Source>): Promise<string>;
+};
+//#endregion
+export type { ExcerptOptions, ReadingTimeOptions, TextFormat, TextOptions };

package/dist/computed.mjs

@@ -0,0 +1,139 @@
+import { t as assertServerOnly } from "./server-only-CIJUlyL-.mjs";
+import { n as number, r as string } from "./schema-C5Str-E8.mjs";
+import { t as src_default } from "./dist-C7_FOzY_.mjs";
+import getReadingTime from "reading-time";
+import { Parser } from "htmlparser2";
+//#region src/computed/plain-text.ts
+const markdown = new src_default({ html: true });
+const ignoredElements = /* @__PURE__ */ new Set([
+	"head",
+	"script",
+	"style",
+	"template",
+	"noscript"
+]);
+const blockElements = /* @__PURE__ */ new Set([
+	"address",
+	"article",
+	"aside",
+	"blockquote",
+	"br",
+	"caption",
+	"dd",
+	"details",
+	"dialog",
+	"div",
+	"dl",
+	"dt",
+	"fieldset",
+	"figcaption",
+	"figure",
+	"footer",
+	"form",
+	"h1",
+	"h2",
+	"h3",
+	"h4",
+	"h5",
+	"h6",
+	"header",
+	"hr",
+	"li",
+	"main",
+	"nav",
+	"ol",
+	"p",
+	"pre",
+	"section",
+	"summary",
+	"table",
+	"tbody",
+	"td",
+	"tfoot",
+	"th",
+	"thead",
+	"tr",
+	"ul"
+]);
+/** Extracts HTML text and image alternatives without executing markup or retaining hidden code. */
+function htmlText(html) {
+	const parts = [];
+	let ignoredDepth = 0;
+	new Parser({
+		onopentag(name, attributes) {
+			if (ignoredDepth || ignoredElements.has(name) || Object.hasOwn(attributes, "hidden")) {
+				ignoredDepth++;
+				return;
+			}
+			if (blockElements.has(name)) parts.push(" ");
+			if (name === "img" && attributes.alt) parts.push(" ", attributes.alt, " ");
+		},
+		ontext(text) {
+			if (!ignoredDepth) parts.push(text);
+		},
+		onclosetag(name) {
+			if (ignoredDepth) ignoredDepth--;
+			else if (blockElements.has(name)) parts.push(" ");
+		}
+	}).end(html);
+	return parts.join("");
+}
+/** Normalizes captured Markdown, HTML, or literal text to whitespace-separated plain text. */
+function plainText(input, format) {
+	return (format === "text" ? input : htmlText(format === "markdown" ? markdown.render(input) : input)).replace(/\s+/gu, " ").trim();
+}
+//#endregion
+//#region src/computed/text.ts
+assertServerOnly();
+/** Binds a typed result schema and text operation to the existing computed-field resolver contract. */
+function textField(schema, options, compute) {
+	const { from, format = "markdown" } = options;
+	if (![
+		"markdown",
+		"text",
+		"html"
+	].includes(format)) throw new TypeError("Text format must be \"markdown\", \"text\", or \"html\".");
+	if (from !== void 0 && typeof from !== "function") throw new TypeError("Text from must be a function.");
+	return {
+		schema,
+		/** Resolves selected text during preparation and honors cancellation around asynchronous input. */
+		async resolve(context) {
+			context.signal.throwIfAborted();
+			const input = await (from ? from(context) : context.readBody());
+			context.signal.throwIfAborted();
+			if (input !== void 0 && typeof input !== "string") throw new TypeError("Computed text input must be a string or undefined.");
+			return compute(plainText(input ?? "", format));
+		}
+	};
+}
+/** Creates a numeric computed field counting normalized text with reading-time's word boundaries. */
+function wordCount(options = {}) {
+	return textField(number().int().nonnegative(), options, (text) => getReadingTime(text).words);
+}
+/** Creates a numeric computed field estimating whole reading minutes, rounded up; empty text returns zero. */
+function readingTime(options = {}) {
+	const { wordsPerMinute = 200 } = options;
+	if (!Number.isFinite(wordsPerMinute) || wordsPerMinute <= 0) throw new TypeError("wordsPerMinute must be a finite positive number.");
+	return textField(number().int().nonnegative(), options, (text) => Math.ceil(getReadingTime(text, { wordsPerMinute }).minutes));
+}
+const graphemes = new Intl.Segmenter("en", { granularity: "grapheme" });
+/** Truncates at a word boundary where possible, preserving complete Unicode graphemes and the hard limit. */
+function truncate(text, maxLength) {
+	const characters = [];
+	for (const { segment } of graphemes.segment(text)) {
+		characters.push(segment);
+		if (characters.length > maxLength) break;
+	}
+	if (characters.length <= maxLength) return text;
+	const prefix = characters.slice(0, maxLength - 1).join("").trimEnd();
+	const boundary = prefix.lastIndexOf(" ");
+	return `${characters[maxLength - 1] === " " || boundary < 0 ? prefix : prefix.slice(0, boundary)}…`;
+}
+/** Creates a string computed field containing a normalized plain-text excerpt with a bounded length. */
+function excerpt(options = {}) {
+	const { maxLength = 160 } = options;
+	if (!Number.isSafeInteger(maxLength) || maxLength <= 0) throw new TypeError("maxLength must be a positive safe integer.");
+	return textField(string(), options, (text) => truncate(text, maxLength));
+}
+//#endregion
+export { excerpt, readingTime, wordCount };

package/dist/content-G69dPPuo.d.mts

@@ -0,0 +1,109 @@
+import { n as ContentRenderResult } from "./types-Dh-Sydyw.mjs";
+import { c as Relationship, i as CollectionRegistry, l as RelationshipsOf, s as QueryData } from "./types-C-kdMblM.mjs";
+import { _ as QueryPlan, n as RelationalQueries, t as RelationalCountOptions, u as Query, v as QueryRegistry } from "./relational-types-DgK3rLuw.mjs";
+//#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/query/select.d.ts
+/** A selection whose collection and selected result are inferred when from() is supplied. */
+type SelectFrom<Registry extends CollectionRegistry, Keys extends readonly string[]> = {
+  /** Binds the collection and rejects selected keys that are absent from its prepared data type. */
+  from<Name extends keyof Registry & string>(collection: Name & (Exclude<Keys[number], keyof QueryData<Registry[NoInfer<Name>]>> extends never ? unknown : never)): Query<Registry, Name, Keys extends readonly [] ? QueryData<Registry[Name]> : { [Key in Keys[number]]-?: Key extends keyof QueryData<Registry[Name]> ? QueryData<Registry[Name]>[Key] : never; }, true>;
+};
+//#endregion
+//#region src/shared/errors.d.ts
+type ContentErrorCode = "variant-not-found" | "not-renderable" | "source-error" | "validation-error" | "duplicate-id" | "invalid-reference" | "invalid-query" | "artifact-error" | "render-error";
+type ContentDiagnostic = {
+  code: ContentErrorCode;
+  message: string;
+  operation?: string;
+  collection?: string;
+  id?: string;
+  source?: string;
+  path?: readonly PropertyKey[];
+  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 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/runtime/revision.d.ts
+type QueryRecord = Record<string, unknown> & {
+  id: string;
+};
+/** 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>>;
+  sources?: ReadonlyMap<string, string | undefined>;
+};
+type PreparedRevision = {
+  registry: QueryRegistry;
+  collections: Record<string, PreparedCollection>;
+  relations: Map<string, Map<string, readonly QueryRecord[]>>;
+  active: number;
+  payloadCache: Map<string, Promise<BuiltinPayload>>;
+  renderCache: Map<string, Promise<ContentRenderResult>>;
+  renderMarkdown?: (body: string) => Promise<ContentRenderResult>;
+  execute?: (plan: QueryPlan, terminal: "all" | "first" | "count", 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
+//#region src/runtime/content.d.ts
+type ContentMethods<Registry extends CollectionRegistry = {}> = {
+  /** Starts a SQL-ordered fluent query; field names are checked against the collection in from(). */
+  select<const Keys extends readonly string[]>(...fields: Keys): SelectFrom<Registry, Keys>;
+  /** Collection-scoped relational queries with typed columns, relationships, payloads, and filters. */
+  readonly query: RelationalQueries<Registry>;
+  /** Counts matching entries before pagination, like the fluent count terminal. */
+  count<Name extends keyof Registry & string>(collection: Name, options?: RelationalCountOptions<Registry, Name>): Promise<number>;
+};
+type Content<Registry extends CollectionRegistry = {}> = InvalidRelationships<Registry> extends never ? ContentMethods<Registry> : {
+  readonly invalidRelationships: InvalidRelationships<Registry>;
+};
+/** Keeps dev builders live across host-delivered revisions while pinning active operations. */
+declare function createLiveRuntime(initial: ContentState): {
+  content: ContentMethods<CollectionRegistry>;
+  update(next: ContentState): void;
+};
+//#endregion
+export { ContentError as a, ContentDiagnostic as i, createLiveRuntime as n, ContentErrorCode as o, PreparedRevision as r, InvalidRelationships as s, Content as t };