content-query 0.0.2 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yangshun Tay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,92 @@
-Contact me via [GitHub](https://github.com/yangshun) / [LinkedIn](https://linkedin/in/yangshun) / [X](https://x.com/yangshun) if you're interested in this package name. 
+# ContentQuery
 
-In most cases I'm happy to just transfer it to you if you have a serious use.
+Typed collections and queries for Markdown, JSON, YAML, and TOML. ContentQuery validates your content at build time and produces portable data your application can query and render on the server.
+
+Use it with your existing framework. Your application owns its routes, layouts, and public URLs; production reads prepared content without loading the original source files.
+
+## Features
+
+- **Typed schemas.** Validate metadata with bundled schema builders or any Standard Schema V1 provider, with inferred TypeScript types.
+- **Flexible sources.** Load local files, use Astro-compatible content loaders, or write your own loader.
+- **Queries and relationships.** Select fields, filter, sort, paginate, and load related entries with validated references.
+- **Markdown rendering.** Request HTML, headings, and syntax highlighting as query payloads, loaded only when a query asks for them.
+- **Framework integrations.** Use Vite, Next.js, or the standalone CLI, with content updates during development.
+
+## Usage
+
+Requires Node.js 22.12 or later. Install ContentQuery:
+
+```sh
+npm install content-query
+```
+
+Define `content-query.config.ts`:
+
+```ts
+import { defineCollection } from "content-query";
+import { schema } from "content-query/schema";
+
+export const collections = {
+  posts: defineCollection({
+    source: "./content/posts",
+    schema: schema.object({
+      title: schema.string(),
+      draft: schema.boolean().default(false),
+    }),
+  }),
+};
+```
+
+Add Markdown files with `title` frontmatter under `content/posts/`, then build:
+
+```sh
+npx content-query build
+```
+
+Query the generated module from server code:
+
+```ts
+import { content } from "./.content-query/server.js";
+import { eq } from "content-query/query";
+
+const posts = await content
+  .select("id", "title")
+  .from("posts")
+  .where((fields) => eq(fields.draft, false))
+  .orderBy("title");
+
+const post = await content.query.posts.findFirst({
+  where: { id: posts[0]!.id },
+  payloads: { _rendered: true },
+});
+const { html, headings } = post!._payloads._rendered;
+```
+
+Add `.content-query/` to `.gitignore`. Follow the quick start for a complete walkthrough, or choose a framework example below.
+
+## Migrating to 0.2
+
+Version 0.2.0 removes `content.readBody()` and `content.render()`. Request bodies and rendered output as payloads in the query that loads the entry:
+
+| 0.1                                   | 0.2                                                                                                            |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `await content.readBody("posts", id)` | `(await content.query.posts.findFirst({ where: { id }, payloads: { _body: true } }))?._payloads._body`         |
+| `await content.render("posts", id)`   | `(await content.query.posts.findFirst({ where: { id }, payloads: { _rendered: true } }))?._payloads._rendered` |
+| Fluent queries                        | Add `.withPayload("_rendered")` or `.withPayload("_body")` before the terminal.                                |
+
+Built-in payload names start with an underscore: `_body` and `_rendered`. A query for a missing entry returns `undefined` instead of rejecting with `entry-not-found`, which no longer exists. JSON, YAML, and TOML sources and `file()` collections offer no payloads. Rebuild generated content after upgrading; 0.1 artifacts are rejected.
+
+## Documentation
+
+- [Quick start](https://github.com/yangshun/content-query/blob/main/website/content/guides/quick-start.md)
+- [Framework examples](https://github.com/yangshun/content-query/blob/main/examples/README.md)
+- [API and usage](https://github.com/yangshun/content-query/blob/main/docs/API.md)
+- [Guides and reference](https://github.com/yangshun/content-query/blob/main/docs/README.md)
+
+The Vite integration supports Vite 8, and the Next.js integration supports Next.js 16. Both integrations are optional; standalone builds and queries require neither framework.
+
+Pass `contentQuery()` directly to Vite or Vite+'s `plugins` array. No `Plugin` type cast is needed; workspace consumers share the pinned toolchain versions in the dependency catalog.
+
+Repository development checks package types and isolated consumers with [tsrs](https://github.com/oxc-project/tsrs). Run `vp run check` in the package directory for formatting, linting, and type checks; build tools use the shared TypeScript 6 compatibility package for its `6.0.3` JavaScript API. Native TypeScript `7.1.0-beta` is available at the repository root as `vp exec tsc`.
+
+Released under the [MIT license](https://github.com/yangshun/content-query/blob/main/LICENSE).

package/dist/build-DfKd2bpf.d.mts

@@ -0,0 +1,25 @@
+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 };