Package Exports

@contentrain/query
@contentrain/query/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@contentrain/query) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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

# Using npm
npm install @contentrain/query

# Using yarn
yarn add @contentrain/query

# Using pnpm
pnpm add @contentrain/query

Usage

JSON-based Usage (Original)

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)

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

// JSON-based relation loading
const posts = await sdk.query('posts')
  .include('author')
  .get();

SQLite Relations

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

// 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)

class ContentrainSDK {
  constructor(options: ContentLoaderOptions)
  query<T extends QueryConfig>(model: string): ContentrainQueryBuilder<T>
  load<T>(model: string): Promise<LoaderResult<T>>
}

SQLiteQueryBuilder (SQLite Extension)

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

// ✅ 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

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

Initialize SQLite database
Import JSON content
Set up relations
Update queries to use SQLiteQueryBuilder
Test and verify data integrity

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT