@contentrain/query 4.0.0 → 5.0.1

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,260 +1,253 @@
-# @contentrain/query
-
-Core package of the Contentrain SDK. Originally designed for JSON-based content management, now extended with SQLite integration for enhanced performance and scalability.
-
-## Features
-
-### Core Features (JSON-based)
-- 📦 JSON file-based content management
-- 🌍 Multi-language support with JSON files
-- 💾 LRU caching with size-based eviction
-- 🔍 Type-safe query operations
-- 📝 Full TypeScript support
-
-### SQLite Extension Features
-- 🚀 High-performance SQLite database integration
-- 🔄 Advanced relation management (One-to-One & One-to-Many)
-- 🗃️ Efficient data indexing and querying
-- 🔒 Thread-safe database operations
-- 📊 Advanced filtering and sorting
-- 🎯 Efficient pagination
-- 🌐 Enhanced translation support
-
-## Installation
-
-```bash
-# Using npm
-npm install @contentrain/query
-
-# Using yarn
-yarn add @contentrain/query
-
-# Using pnpm
-pnpm add @contentrain/query
-```
-
-## Usage
-
-### JSON-based Usage (Original)
-
-```typescript
-import { ContentrainSDK } from '@contentrain/query';
-
-// Initialize SDK with JSON files
-const sdk = new ContentrainSDK({
-  contentDir: './content',  // Directory containing JSON files
-  defaultLocale: 'en'
-});
-
-// Query JSON content
-const posts = await sdk.query('posts')
-  .where('status', 'eq', 'publish')
-  .get();
-
-// Load with translations
-const trPosts = await sdk.query('posts')
-  .locale('tr')
-  .get();
-```
-
-### SQLite Usage (Extended Feature)
-
-```typescript
-import { SQLiteQueryBuilder, BaseSQLiteLoader } from '@contentrain/query';
-
-// Initialize SQLite loader
-const loader = new BaseSQLiteLoader('path/to/database.db');
-
-// Create SQLite query builder
-const builder = new SQLiteQueryBuilder('posts', loader);
-
-// Execute SQLite query
-const result = await builder
-  .where('status', 'eq', 'publish')
-  .get();
-```
-
-## Data Management
-
-### JSON-based Storage
-- Content stored in JSON files
-- Directory-based organization
-- File-based translations
-- Simple version control with Git
-
-### SQLite Storage
-- Relational database storage
-- Optimized for querying and relations
-- Efficient data indexing
-- Better performance for large datasets
-
-## Relations
-
-### JSON Relations
-```typescript
-// JSON-based relation loading
-const posts = await sdk.query('posts')
-  .include('author')
-  .get();
-```
-
-### SQLite Relations
-```typescript
-interface Post {
-  id: string;
-  title: string;
-  author_id: string;
-  _relations?: {
-    author: Author;
-    categories: Category[];
-  }
-}
-
-// One-to-One in SQLite
-const post = await builder
-  .include('author')
-  .where('id', 'eq', '123')
-  .first();
-
-// One-to-Many in SQLite
-const postWithCategories = await builder
-  .include('categories')
-  .where('id', 'eq', '123')
-  .first();
-```
-
-## Translations
-
-### JSON Translations
-- Separate JSON files for each locale
-- File-based translation management
-- Git-friendly structure
-
-### SQLite Translations
-```typescript
-// Dedicated translation tables
-const trPost = await builder
-  .locale('tr')
-  .where('id', 'eq', '123')
-  .first();
-
-// Fallback support
-const result = await builder
-  .locale('tr')
-  .include(['author', 'categories'])
-  .get();
-```
-
-## API Reference
-
-### ContentrainSDK (JSON-based)
-```typescript
-class ContentrainSDK {
-  constructor(options: ContentLoaderOptions)
-  query<T extends QueryConfig>(model: string): ContentrainQueryBuilder<T>
-  load<T>(model: string): Promise<LoaderResult<T>>
-}
-```
-
-### SQLiteQueryBuilder (SQLite Extension)
-```typescript
-class SQLiteQueryBuilder<T extends DBRecord> {
-  constructor(model: string, connection: BaseSQLiteLoader)
-
-  // Query Methods
-  where<K extends keyof T>(
-    field: K,
-    operator: Operator,
-    value: T[K] | T[K][]
-  ): this
-
-  include(relations: string | string[]): this
-  orderBy(field: keyof T, direction?: 'asc' | 'desc'): this
-  limit(count: number): this
-  offset(count: number): this
-  locale(code: string): this
-
-  // Execution Methods
-  get(): Promise<QueryResult<T>>
-  first(): Promise<T | null>
-  count(): Promise<number>
-}
-```
-
-## Best Practices
-
-### JSON vs SQLite Usage
-
-```typescript
-// ✅ Use JSON when:
-// - Small to medium dataset
-// - Git-based version control is priority
-// - Simple content structure
-const posts = await sdk.query('posts').get();
-
-// ✅ Use SQLite when:
-// - Large dataset
-// - Complex relations
-// - Performance is critical
-// - Advanced querying needed
-const posts = await builder
-  .where('status', 'eq', 'publish')
-  .include(['author', 'categories'])
-  .orderBy('created_at', 'desc')
-  .limit(10)
-  .get();
-```
-
-### Performance Considerations
-
-#### JSON Storage
-- Keep files organized in directories
-- Use appropriate file naming
-- Consider file size for large datasets
-
-#### SQLite Storage
-- Use appropriate indexes
-- Optimize relation queries
-- Implement pagination
-- Use eager loading for relations
-
-## Error Handling
-
-```typescript
-try {
-  const result = await builder
-    .where('status', 'eq', 'publish')
-    .get();
-} catch (error) {
-  if (error instanceof SQLiteError) {
-    // Handle SQLite specific errors
-  } else if (error instanceof ValidationError) {
-    // Handle validation errors
-  } else if (error instanceof RelationError) {
-    // Handle relation errors
-  } else if (error instanceof FileSystemError) {
-    // Handle JSON file system errors
-  }
-}
-```
-
-## Migration Guide
-
-### From JSON to SQLite
-1. Initialize SQLite database
-2. Import JSON content
-3. Set up relations
-4. Update queries to use SQLiteQueryBuilder
-5. Test and verify data integrity
-
-## Contributing
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-## License
-
-MIT
+# `@contentrain/query`
+
+[![npm version](https://img.shields.io/npm/v/%40contentrain%2Fquery?label=%40contentrain%2Fquery)](https://www.npmjs.com/package/@contentrain/query)
+[![GitHub source](https://img.shields.io/badge/source-Contentrain%2Fai-181717?logo=github)](https://github.com/Contentrain/ai/tree/main/packages/sdk/js)
+
+**Optional** type-safe generated query SDK for Contentrain.
+
+Contentrain stores content as plain JSON and Markdown in a git-backed `.contentrain/` directory. Any platform that reads JSON can consume this content directly. This package adds a TypeScript convenience layer that turns content models 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
+
+## 📚 Documentation
+
+Full documentation at **[ai.contentrain.io/packages/sdk](https://ai.contentrain.io/packages/sdk)**.
+
+## 📄 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 { };