@contentrain/query 3.2.0 → 5.0.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 Contentrain
-
-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.
+MIT License
+
+Copyright (c) 2026 Contentrain
+
+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,268 +1,246 @@
-# @contentrain/query
-
-Core package of the Contentrain SDK. This package provides the fundamental functionality and types for interacting with Contentrain CMS.
-
-## Features
-
-- 🚀 High-performance content loading
-- 💾 LRU caching with size-based eviction
-- 🔍 Advanced query capabilities with type-safe operators
-- 📦 Full TypeScript support with generic types
-- 🛡️ Comprehensive error handling
-- ⚡ Memory-optimized performance
-- 🌍 Multi-language support
-- 🔄 Relation resolution
-
-## Installation
-
-```bash
-# Using npm
-npm install @contentrain/query
-
-# Using yarn
-yarn add @contentrain/query
-
-# Using pnpm
-pnpm add @contentrain/query
-```
-
-## Usage
-
-### Content Loading
-
-```typescript
-import { ContentLoader } from '@contentrain/query';
-
-const loader = new ContentLoader({
-  contentDir: './content',
-  defaultLocale: 'en',
-  cache: true,
-  ttl: 60 * 1000, // 1 minute
-  maxCacheSize: 100 // 100 MB
-});
-
-// Load all blog posts
-const posts = await loader.load('posts');
-
-// Load with locale
-const trPosts = await loader.load('posts').locale('tr');
-
-// Error handling
-try {
-  const post = await loader.load('posts', 'non-existent-post');
-} catch (error) {
-  if (error instanceof ContentNotFoundError) {
-    console.error('Post not found');
-  } else if (error instanceof ContentValidationError) {
-    console.error('Content validation failed');
-  }
-}
-```
-
-### Query Operations
-
-```typescript
-import { ContentrainSDK } from '@contentrain/query';
-
-const sdk = new ContentrainSDK({
-  contentDir: './content'
-});
-
-// Type-safe querying
-interface Post {
-  ID: string;
-  title: string;
-  status: 'draft' | 'published';
-  tags: string[];
-  createdAt: string;
-}
-
-const query = sdk.query<{
-  fields: Post;
-  locales: 'en' | 'tr';
-  relations: {
-    author: Author;
-    categories: Category[];
-  }
-}>('posts');
-
-// Available operators
-const posts = await query
-  .where('status', 'eq', 'published')
-  .where('tags', 'contains', ['javascript'])
-  .where('createdAt', 'gt', '2024-01-01')
-  .where('category', 'in', ['tech', 'programming'])
-  .orderBy('createdAt', 'desc')
-  .limit(5)
-  .get();
-
-// Relation handling
-const postsWithRelations = await query
-  .include(['author', 'categories'])
-  .where('status', 'eq', 'published')
-  .get();
-
-// Locale support
-const trPosts = await query
-  .locale('tr')
-  .where('status', 'eq', 'published')
-  .get();
-```
-
-### Caching
-
-```typescript
-import { MemoryCache } from '@contentrain/query';
-
-const cache = new MemoryCache({
-  maxSize: 100, // Maximum cache size in MB
-  defaultTTL: 60 * 1000, // Default TTL in ms
-});
-
-// Set with custom TTL
-await cache.set('key', data, 5 * 60 * 1000); // 5 minutes TTL
-
-// Get with type safety
-const data = await cache.get<Post[]>('key');
-
-// Cache stats
-const stats = cache.getStats();
-console.log(`
-  Hits: ${stats.hits}
-  Misses: ${stats.misses}
-  Size: ${stats.size} bytes
-  Last Cleanup: ${stats.lastCleanup}
-`);
-```
-
-## API Reference
-
-### ContentrainSDK
-
-Main entry point for the SDK.
-
-```typescript
-class ContentrainSDK {
-  constructor(options: ContentLoaderOptions)
-  query<T extends QueryConfig>(model: string): ContentrainQueryBuilder<T>
-  load<T>(model: string): Promise<LoaderResult<T>>
-}
-```
-
-### Query Builder
-
-```typescript
-interface QueryBuilder<T> {
-  // Filter operations
-  where<K extends keyof T>(
-    field: K,
-    operator: QueryOperator,
-    value: T[K] | T[K][]
-  ): this
-
-  // Available operators:
-  // 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' |
-  // 'in' | 'nin' | 'contains' | 'startsWith' | 'endsWith'
-
-  // Relation operations
-  include(relations: string | string[]): this
-
-  // Sorting
-  orderBy(field: keyof T, direction?: 'asc' | 'desc'): this
-
-  // Pagination
-  limit(count: number): this
-  offset(count: number): this
-
-  // Locale
-  locale(code: string): this
-
-  // Cache control
-  cache(ttl?: number): this
-  noCache(): this
-  bypassCache(): this
-
-  // Execution
-  get(): Promise<QueryResult<T>>
-  first(): Promise<T | null>
-  count(): Promise<number>
-}
-
-interface QueryResult<T> {
-  data: T[]
-  total: number
-  pagination?: {
-    limit: number
-    offset: number
-    hasMore: boolean
-  }
-}
-```
-
-### Cache Manager
-
-```typescript
-interface CacheManager {
-  set<T>(key: string, value: T, ttl?: number): Promise<void>
-  get<T>(key: string): Promise<T | null>
-  delete(key: string): Promise<void>
-  clear(): Promise<void>
-  getStats(): CacheStats
-}
-
-interface CacheStats {
-  hits: number
-  misses: number
-  size: number
-  lastCleanup: number
-}
-```
-
-### Content Loader
-
-```typescript
-interface ContentLoader {
-  load<T>(model: string): Promise<LoaderResult<T>>
-  resolveRelation<T, R>(
-    model: string,
-    relationField: keyof T,
-    data: T[],
-    locale?: string
-  ): Promise<R[]>
-  clearCache(): Promise<void>
-  refreshCache(model: string): Promise<void>
-  getCacheStats(): CacheStats
-}
-```
-
-## Error Handling
-
-The package provides specific error types for different scenarios:
-
-```typescript
-import {
-  ContentrainError, // Base error class
-  ContentNotFoundError,
-  ContentValidationError,
-  CacheError,
-  RelationError
-} from '@contentrain/query';
-
-try {
-  const posts = await loader.load('posts');
-} catch (error) {
-  if (error instanceof ContentNotFoundError) {
-    // Handle not found
-  } else if (error instanceof ContentValidationError) {
-    // Handle validation errors
-  } else if (error instanceof CacheError) {
-    // Handle cache errors
-  } else if (error instanceof RelationError) {
-    // Handle relation errors
-  }
-}
-```
-
-## License
-
-MIT
+# `@contentrain/query`
+
+Type-safe generated query SDK for Contentrain.
+
+Contentrain stores content in a git-backed `.contentrain/` directory. This package turns that content model into a generated JS/TS client with:
+
+- exact TypeScript types from your models
+- zero-dependency query runtime
+- Node `#contentrain` subpath imports
+- ESM and CommonJS output
+- framework-agnostic usage across app and server environments
+
+## 🚀 Install
+
+```bash
+pnpm add @contentrain/query
+```
+
+Requirements:
+
+- Node.js `22+`
+- a Contentrain project with `.contentrain/config.json`
+
+## ✨ What This Package Provides
+
+`@contentrain/query` has two roles:
+
+1. **Generator**
+   - reads `.contentrain/config.json`, models, and content files
+   - writes `.contentrain/client/`
+   - injects `#contentrain` imports into your `package.json`
+
+2. **Base runtime**
+   - exports low-level runtime classes for framework SDK authors
+   - exports `createContentrainClient(projectRoot?)` for loading a generated client module
+
+## 🚀 Quick Start
+
+Generate a client:
+
+```bash
+npx contentrain-query generate
+```
+
+This writes:
+
+```text
+.contentrain/client/
+  index.mjs
+  index.cjs
+  index.d.ts
+  data/*
+```
+
+It also updates your `package.json` with:
+
+```json
+{
+  "imports": {
+    "#contentrain": {
+      "types": "./.contentrain/client/index.d.ts",
+      "import": "./.contentrain/client/index.mjs",
+      "require": "./.contentrain/client/index.cjs",
+      "default": "./.contentrain/client/index.mjs"
+    }
+  }
+}
+```
+
+Then use the generated client in your app:
+
+```ts
+import { query, singleton, dictionary, document } from '#contentrain'
+
+const posts = query('blog-post')
+  .locale('en')
+  .where('status', 'published')
+  .sort('title')
+  .all()
+
+const hero = singleton('hero').locale('en').get()
+const messages = dictionary('error-messages').locale('en').get()
+const article = document('blog-article').locale('en').bySlug('welcome-post')
+```
+
+## 📦 Generated Client API
+
+The generated client exposes four entry points:
+
+### `query(model)`
+
+For collection models.
+
+Supported methods:
+
+- `locale(lang)`
+- `where(field, value)`
+- `sort(field, order?)`
+- `limit(n)`
+- `offset(n)`
+- `include(...fields)`
+- `first()`
+- `all()`
+
+### `singleton(model)`
+
+For singleton models.
+
+Supported methods:
+
+- `locale(lang)`
+- `include(...fields)`
+- `get()`
+
+### `dictionary(model)`
+
+For dictionary models.
+
+Supported methods:
+
+- `locale(lang)`
+- `get()`
+- `get(key)`
+
+### `document(model)`
+
+For markdown/document models.
+
+Supported methods:
+
+- `locale(lang)`
+- `where(field, value)`
+- `include(...fields)`
+- `bySlug(slug)`
+- `first()`
+- `all()`
+
+## 🔗 Relations
+
+Generated clients support relation resolution via `include(...)`.
+
+Examples:
+
+```ts
+const posts = query('blog-post')
+  .locale('en')
+  .include('author', 'tags')
+  .all()
+
+const settings = singleton('site-settings')
+  .locale('en')
+  .include('featured_post')
+  .get()
+```
+
+## 🧱 Framework SDK Authors
+
+The package root exports runtime primitives and an async loader:
+
+```ts
+import { createContentrainClient } from '@contentrain/query'
+
+const client = await createContentrainClient(process.cwd())
+const posts = client.query('blog-post').locale('en').all()
+```
+
+Public root exports:
+
+- `QueryBuilder`
+- `SingletonAccessor`
+- `DictionaryAccessor`
+- `DocumentQuery`
+- `createContentrainClient`
+
+## 🧩 CommonJS Usage
+
+Generated clients support CommonJS through `init()`:
+
+```js
+const clientModule = require('#contentrain')
+const client = await clientModule.init()
+
+const hero = client.singleton('hero').get()
+```
+
+## 🛠 CLI
+
+Generate once:
+
+```bash
+npx contentrain-query generate
+```
+
+Generate in watch mode:
+
+```bash
+npx contentrain-query generate --watch
+```
+
+Use a different project root:
+
+```bash
+npx contentrain-query generate --root /path/to/project
+```
+
+## 📤 Package Exports
+
+Main package:
+
+- `@contentrain/query`
+
+Generator entry:
+
+- `@contentrain/query/generate`
+
+## 🧠 Design Constraints
+
+This package intentionally:
+
+- generates into `.contentrain/client/` instead of `node_modules`
+- uses `package.json#imports` instead of custom alias plugins
+- ships zero-dependency runtime classes
+- keeps the runtime framework-agnostic
+- treats generated client output as the primary consumer surface
+
+## 🛠 Development
+
+From the monorepo root:
+
+```bash
+pnpm --filter @contentrain/query build
+pnpm --filter @contentrain/query test
+pnpm --filter @contentrain/query typecheck
+pnpm exec oxlint packages/sdk/js/src packages/sdk/js/tests
+```
+
+## 🔗 Related Packages
+
+- `contentrain` — CLI that runs project initialization, validation, serve, and generation flows
+- `@contentrain/mcp` — local-first MCP server and core content workflow engine
+- `@contentrain/types` — shared schema and model definitions
+- `@contentrain/rules` — agent rules and prompts
+
+## 📄 License
+
+MIT

package/dist/cli.cjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+const require_generate = require("./generate-CPKYh6ZU.cjs");
+let node_path = require("node:path");
+let node_fs = require("node:fs");
+//#region src/cli.ts
+async function main() {
+	const args = process.argv.slice(2);
+	if (args[0] !== "generate" && args.length === 0) {
+		console.log("Usage: contentrain-query generate [--root <path>] [--watch]");
+		console.log("");
+		console.log("Commands:");
+		console.log("  generate    Generate typed client from .contentrain/ project files");
+		console.log("");
+		console.log("Options:");
+		console.log("  --root      Project root directory (default: cwd)");
+		console.log("  --watch     Watch for changes and regenerate automatically");
+		process.exit(0);
+	}
+	const command = args[0] === "generate" ? "generate" : args[0];
+	if (command !== "generate") {
+		console.error(`Unknown command: ${command}`);
+		process.exit(1);
+	}
+	const rootIdx = args.indexOf("--root");
+	const rootArg = rootIdx !== -1 ? args[rootIdx + 1] : void 0;
+	const projectRoot = rootArg ? (0, node_path.resolve)(rootArg) : process.cwd();
+	const watchMode = args.includes("--watch");
+	try {
+		const result = await require_generate.generate({ projectRoot });
+		console.log(`@contentrain/query — generated client`);
+		console.log(`  Models:       ${result.typesCount}`);
+		console.log(`  Data modules: ${result.dataModulesCount}`);
+		console.log(`  Files:        ${result.generatedFiles.length}`);
+		if (result.packageJsonUpdated) console.log(`  package.json: #contentrain imports added`);
+		console.log(`  Output:       .contentrain/client/`);
+		if (watchMode) startWatch(projectRoot);
+	} catch (err) {
+		console.error("Generate failed:", err.message);
+		process.exit(1);
+	}
+}
+function startWatch(projectRoot) {
+	const crDir = (0, node_path.join)(projectRoot, ".contentrain");
+	const modelsDir = (0, node_path.join)(crDir, "models");
+	const contentDir = (0, node_path.join)(crDir, "content");
+	const configFile = (0, node_path.join)(crDir, "config.json");
+	let debounceTimer = null;
+	const regenerate = async () => {
+		try {
+			const result = await require_generate.generate({ projectRoot });
+			console.log(`  Regenerated: ${result.typesCount} models, ${result.dataModulesCount} data modules`);
+		} catch (err) {
+			console.error("  Regenerate failed:", err.message);
+		}
+	};
+	const onChange = (_event, filename) => {
+		if (filename && filename.startsWith("client")) return;
+		if (debounceTimer) clearTimeout(debounceTimer);
+		debounceTimer = setTimeout(() => {
+			console.log(`  Change detected: ${filename ?? "unknown"}`);
+			regenerate();
+		}, 150);
+	};
+	try {
+		(0, node_fs.watch)(modelsDir, { recursive: true }, onChange);
+	} catch {}
+	try {
+		(0, node_fs.watch)(contentDir, { recursive: true }, onChange);
+	} catch {}
+	try {
+		(0, node_fs.watch)(configFile, onChange);
+	} catch {}
+	console.log("");
+	console.log("Watching for changes in .contentrain/ ...");
+	console.log("Press Ctrl+C to stop.");
+}
+main();
+//#endregion

package/dist/cli.d.cts

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

package/dist/cli.d.mts

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