@contentrain/query 2.0.1 → 3.1.0

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -1,134 +1,268 @@
 # @contentrain/query
 
-Query builder for Contentrain SDK.
+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
-npm install @contentrain/query @contentrain/core
+# Using npm
+npm install @contentrain/query
+
+# Using yarn
+yarn add @contentrain/query
+
+# Using pnpm
+pnpm add @contentrain/query
 ```
 
 ## Usage
 
+### Content Loading
+
 ```typescript
-import { ContentrainCore } from '@contentrain/core'
-import { ContentrainQuery } from '@contentrain/query'
+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');
+  }
+}
+```
 
-// Initialize core and query
-const core = new ContentrainCore()
-const query = new ContentrainQuery(core)
+### Query Operations
 
-// Basic query
+```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
-  .from('posts')
-  .where('status', 'publish')
-  .get()
-
-// Complex query
-const featuredPosts = await query
-  .from('posts')
-  .where('status', 'publish')
-  .where('featured', true)
+  .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()
-
-// Query with relations
-const postsWithAuthor = await query
-  .from('posts')
-  .with('author')
-  .where('status', 'publish')
-  .get()
-
-// Query with multiple conditions
-const searchPosts = await query
-  .from('posts')
-  .where([
-    ['status', 'publish'],
-    ['category', 'technology'],
-    ['title', 'startsWith', 'How to']
-  ])
-  .get()
+  .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();
 ```
 
-## API Reference
-
-### Constructor
+### Caching
 
 ```typescript
-constructor(core: ContentrainCore)
+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}
+`);
 ```
 
-Creates a new instance of ContentrainQuery.
-
-### Methods
+## API Reference
 
-#### from
-```typescript
-from(collection: string): ContentrainQuery
-```
+### ContentrainSDK
 
-Specifies the collection to query.
+Main entry point for the SDK.
 
-#### where
 ```typescript
-where(field: string, value: any): ContentrainQuery
-where(field: string, operator: FilterOperator, value: any): ContentrainQuery
-where(conditions: [string, any][] | [string, FilterOperator, any][]): ContentrainQuery
+class ContentrainSDK {
+  constructor(options: ContentLoaderOptions)
+  query<T extends QueryConfig>(model: string): ContentrainQueryBuilder<T>
+  load<T>(model: string): Promise<LoaderResult<T>>
+}
 ```
 
-Adds where conditions to the query.
+### Query Builder
 
-#### orderBy
 ```typescript
-orderBy(field: string, direction: 'asc' | 'desc' = 'asc'): ContentrainQuery
+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
+  }
+}
 ```
 
-Orders the results by a field.
+### Cache Manager
 
-#### limit
 ```typescript
-limit(count: number): ContentrainQuery
+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
+}
 ```
 
-Limits the number of results.
+### Content Loader
 
-#### offset
 ```typescript
-offset(count: number): ContentrainQuery
+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
+}
 ```
 
-Skips the specified number of results.
+## Error Handling
 
-#### with
-```typescript
-with(...relations: string[]): ContentrainQuery
-```
+The package provides specific error types for different scenarios:
 
-Includes related content in the results.
-
-#### get
 ```typescript
-get<T>(): Promise<T[]>
+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
+  }
+}
 ```
 
-Executes the query and returns the results.
-
-### Filter Operators
-
-- `equals` (default)
-- `notEquals`
-- `contains`
-- `notContains`
-- `startsWith`
-- `endsWith`
-- `exists`
-- `notExists`
-- `gt` (greater than)
-- `gte` (greater than or equal)
-- `lt` (less than)
-- `lte` (less than or equal)
-
 ## License
 
 MIT

package/dist/index.d.mts

@@ -1,28 +1,286 @@
-import { IContentrainCore } from '@contentrain/core';
-import { ContentrainBaseModel, FilterCondition, SortDirection, WithRelation } from '@contentrain/types';
+interface ContentrainConfig {
+    contentDir: string;
+    defaultLocale?: string;
+    models: {
+        [modelId: string]: {
+            localized: boolean;
+            defaultLocale?: string;
+            locales?: string[];
+        };
+    };
+}
 
-declare class ContentrainQuery<T extends ContentrainBaseModel> {
-    private core;
-    private collection;
-    private filters;
-    private sorts;
+interface BaseContentrainType {
+    ID: string;
+    createdAt: string;
+    updatedAt: string;
+    status: 'draft' | 'changed' | 'publish';
+    scheduled: boolean;
+    _relations?: {
+        [key: string]: BaseContentrainType | BaseContentrainType[];
+    };
+}
+type ContentrainStatus = 'draft' | 'changed' | 'publish';
+interface ModelMetadata {
+    name: string;
+    modelId: string;
+    localization: boolean;
+    type: 'JSON';
+    createdBy: string;
+    isServerless: boolean;
+}
+interface FieldMetadata {
+    name: string;
+    fieldId: string;
+    modelId: string;
+    componentId: ContentrainComponentId;
+    fieldType: ContentrainFieldType;
+    options: FieldOptions;
+    validations: FieldValidations;
+    system?: boolean;
+    defaultField?: boolean;
+}
+type ContentrainFieldType = 'string' | 'number' | 'boolean' | 'array' | 'date' | 'media' | 'relation';
+type ContentrainComponentId = 'single-line-text' | 'multi-line-text' | 'email' | 'url' | 'slug' | 'color' | 'json' | 'md-editor' | 'rich-text-editor' | 'integer' | 'decimal' | 'rating' | 'percent' | 'phone-number' | 'checkbox' | 'switch' | 'date' | 'date-time' | 'media' | 'one-to-one' | 'one-to-many';
+interface FieldOptions {
+    'title-field'?: {
+        value: boolean;
+    };
+    'default-value'?: {
+        value: boolean;
+        form: {
+            [key: string]: {
+                value: any;
+            };
+        };
+    };
+    'reference'?: {
+        value: boolean;
+        form: {
+            reference: {
+                value: string;
+            };
+        };
+    };
+}
+interface FieldValidations {
+    'required-field'?: {
+        value: boolean;
+    };
+    'unique-field'?: {
+        value: boolean;
+    };
+    'input-range-field'?: {
+        value: {
+            min: number;
+            max: number;
+        };
+    };
+}
+type ContentrainLocales = string;
+
+interface ContentLoaderOptions {
+    contentDir: string;
+    defaultLocale?: string;
+    cache?: boolean;
+    ttl?: number;
+    maxCacheSize?: number;
+    modelTTL?: {
+        [model: string]: number;
+    };
+}
+interface ModelConfig {
+    metadata: ModelMetadata;
+    fields: FieldMetadata[];
+}
+interface ContentFile<T extends BaseContentrainType = BaseContentrainType> {
+    model: string;
+    locale?: string;
+    data: T[];
+}
+interface AssetMetadata {
+    path: string;
+    mimetype: string;
+    size: number;
+    alt: string;
+    meta: {
+        user: {
+            name: string;
+            email: string;
+            avatar: string;
+        };
+        createdAt: string;
+    };
+}
+interface LoaderResult<T extends BaseContentrainType = BaseContentrainType> {
+    model: ModelConfig;
+    content: {
+        [locale: string]: T[];
+    };
+    assets?: AssetMetadata[];
+}
+interface RelationConfig {
+    model: string;
+    type: 'one-to-one' | 'one-to-many';
+    foreignKey: string;
+}
+interface CacheStats {
+    hits: number;
+    misses: number;
+    size: number;
+    lastCleanup: number;
+}
+interface CacheEntry<T> {
+    data: T;
+    expireAt: number;
+    size: number;
+    createdAt: number;
+}
+interface MemoryCacheOptions {
+    maxSize?: number;
+    defaultTTL?: number;
+}
+
+type StringOperator = 'eq' | 'ne' | 'contains' | 'startsWith' | 'endsWith';
+type NumericOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte';
+type ArrayOperator = 'in' | 'nin';
+type Operator = StringOperator | NumericOperator | ArrayOperator;
+interface Filter<T = any> {
+    field: string;
+    operator: Operator;
+    value: T extends Array<infer U> ? (ArrayOperator extends 'in' | 'nin' ? U[] : U) : T;
+}
+interface Sort {
+    field: string;
+    direction: 'asc' | 'desc';
+}
+interface Pagination {
+    limit?: number;
+    offset?: number;
+}
+interface Include {
+    [relation: string]: {
+        fields?: string[];
+        include?: Include;
+    };
+}
+interface QueryOptions {
+    locale?: string;
+    cache?: boolean;
+    ttl?: number;
+}
+interface QueryResult<T> {
+    data: T[];
+    total: number;
+    pagination?: {
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+    };
+}
+interface QueryConfig<TFields extends BaseContentrainType, TLocales extends ContentrainLocales = 'en' | 'tr', TRelations extends Record<string, BaseContentrainType> = Record<string, never>> {
+    fields: TFields;
+    locales: TLocales;
+    relations: TRelations;
+}
+
+declare class ContentLoader {
+    private options;
+    private modelConfigs;
     private relations;
-    private limitCount?;
-    private skipCount?;
-    constructor(core: IContentrainCore | undefined, collection: string);
-    where(field: keyof T, operator: FilterCondition<T>['operator'], value: T[keyof T]): this;
-    sort(field: keyof T, direction?: SortDirection): this;
-    take(limit: number): this;
-    offset(skip: number): this;
-    with(relation: keyof T): this;
-    private getModelMetadata;
-    private getRelatedData;
-    private evaluateFilter;
-    private evaluateSort;
-    get(): Promise<T[]>;
-    getWithRelations<K extends keyof T>(): Promise<WithRelation<T, K>[]>;
-    first(): Promise<T | null>;
-    firstWithRelations<K extends keyof T>(): Promise<WithRelation<T, K> | null>;
-}
-
-export { ContentrainQuery };
+    private cache;
+    constructor(options: ContentLoaderOptions);
+    private getCacheKey;
+    private getModelTTL;
+    clearCache(): Promise<void>;
+    refreshCache(model: string): Promise<void>;
+    getCacheStats(): CacheStats;
+    private loadModelConfig;
+    private loadContentFile;
+    private loadRelations;
+    private getModelLocales;
+    load<T extends BaseContentrainType>(model: string): Promise<LoaderResult<T>>;
+    resolveRelation<T extends BaseContentrainType, R extends BaseContentrainType>(model: string, relationField: keyof T, data: T[], locale?: string): Promise<R[]>;
+}
+
+declare class QueryExecutor {
+    private loader;
+    constructor(loader: ContentLoader);
+    private applyFilters;
+    private applySorting;
+    private applyPagination;
+    private resolveIncludes;
+    private applyStringOperation;
+    execute<T extends BaseContentrainType>({ model, data, filters, includes, sorting, pagination, options, }: {
+        model: string;
+        data: T[];
+        filters?: Filter[];
+        includes?: Include;
+        sorting?: Sort[];
+        pagination?: {
+            limit?: number;
+            offset?: number;
+        };
+        options?: QueryOptions;
+    }): Promise<QueryResult<T>>;
+}
+
+declare class ContentrainQueryBuilder<TFields extends BaseContentrainType, TLocales extends ContentrainLocales = 'en' | 'tr', TRelations extends Record<string, BaseContentrainType> = Record<string, never>> {
+    private model;
+    private filters;
+    private includes;
+    private sorting;
+    private pagination;
+    private options;
+    private executor;
+    private loader;
+    constructor(model: string, executor: QueryExecutor, loader: ContentLoader);
+    where<K extends keyof TFields, O extends Operator>(field: K, operator: O, value: O extends 'in' ? TFields[K][] : TFields[K]): this;
+    include<K extends keyof TRelations>(relation: K | K[]): this;
+    orderBy<K extends keyof TFields>(field: K, direction?: 'asc' | 'desc'): this;
+    limit(count: number): this;
+    offset(count: number): this;
+    locale(code: TLocales): this;
+    cache(ttl?: number): this;
+    noCache(): this;
+    bypassCache(): this;
+    toJSON(): {
+        model: string;
+        filters: Filter<any>[];
+        includes: Include;
+        sorting: Sort[];
+        pagination: Pagination;
+        options: QueryOptions;
+    };
+    get(): Promise<QueryResult<TFields>>;
+    first(): Promise<TFields | null>;
+    count(): Promise<number>;
+}
+
+declare class MemoryCache {
+    private cache;
+    private options;
+    private stats;
+    constructor(options?: MemoryCacheOptions);
+    private calculateSize;
+    set<T>(key: string, data: T, ttl?: number): Promise<void>;
+    private findOldestKey;
+    get<T>(key: string): Promise<T | null>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    private cleanupCache;
+    getStats(): CacheStats;
+}
+
+declare class ContentrainSDK {
+    private loader;
+    private executor;
+    constructor(options: ContentLoaderOptions);
+    query<T extends QueryConfig<BaseContentrainType, string, Record<string, BaseContentrainType>>>(model: string): ContentrainQueryBuilder<T['fields'], T['locales'], T['relations']>;
+    load<T extends BaseContentrainType>(model: string): Promise<LoaderResult<T>>;
+    clearCache(): Promise<void>;
+    refreshCache(model: string): Promise<void>;
+    getCacheStats(): CacheStats;
+}
+
+export { type ArrayOperator, type AssetMetadata, type BaseContentrainType, type CacheEntry, type CacheStats, type ContentFile, ContentLoader, type ContentLoaderOptions, type ContentrainComponentId, type ContentrainConfig, type ContentrainFieldType, type ContentrainLocales, ContentrainQueryBuilder, ContentrainSDK, type ContentrainStatus, type FieldMetadata, type FieldOptions, type FieldValidations, type Filter, type Include, type LoaderResult, MemoryCache, type MemoryCacheOptions, type ModelConfig, type ModelMetadata, type NumericOperator, type Operator, type Pagination, type QueryConfig, QueryExecutor, type QueryOptions, type QueryResult, type RelationConfig, type Sort, type StringOperator };