@trokky/client 2.0.3

package/dist/query/builder.js

@@ -0,0 +1,731 @@
+/**
+ * Fluent Query Builder
+ * Provides a chainable API for building document queries with reference expansion
+ */
+/**
+ * Fluent query builder for Trokky documents
+ *
+ * @example
+ * ```typescript
+ * const articles = await client
+ *   .from('article')
+ *   .published()
+ *   .expand('category')
+ *   .expand('author')
+ *   .sort({ _createdAt: 'desc' })
+ *   .limit(10)
+ *   .fetch()
+ * ```
+ */
+export class QueryBuilder {
+    constructor(http, cache, type) {
+        this.http = http;
+        this.cache = cache;
+        this._filter = {};
+        this._sort = {};
+        this._expand = [];
+        this._options = { useCache: true };
+        this._type = type;
+    }
+    /**
+     * Filter by published status (_status === 'published')
+     */
+    published() {
+        this._filter._status = 'published';
+        return this;
+    }
+    /**
+     * Filter by draft status (_status === 'draft')
+     */
+    draft() {
+        this._filter._status = 'draft';
+        return this;
+    }
+    where(conditionsOrField, value) {
+        if (typeof conditionsOrField === 'string') {
+            this._filter[conditionsOrField] = value;
+        }
+        else {
+            this._filter = { ...this._filter, ...conditionsOrField };
+        }
+        return this;
+    }
+    /**
+     * Add equality filter
+     */
+    eq(field, value) {
+        this._filter[field] = value;
+        return this;
+    }
+    /**
+     * Add not-equal filter
+     */
+    neq(field, value) {
+        this._filter[field] = { $ne: value };
+        return this;
+    }
+    /**
+     * Add greater-than filter
+     */
+    gt(field, value) {
+        this._filter[field] = { $gt: value };
+        return this;
+    }
+    /**
+     * Add greater-than-or-equal filter
+     */
+    gte(field, value) {
+        this._filter[field] = { $gte: value };
+        return this;
+    }
+    /**
+     * Add less-than filter
+     */
+    lt(field, value) {
+        this._filter[field] = { $lt: value };
+        return this;
+    }
+    /**
+     * Add less-than-or-equal filter
+     */
+    lte(field, value) {
+        this._filter[field] = { $lte: value };
+        return this;
+    }
+    /**
+     * Add in-array filter
+     */
+    in(field, values) {
+        this._filter[field] = { $in: values };
+        return this;
+    }
+    /**
+     * Add not-in-array filter
+     */
+    notIn(field, values) {
+        this._filter[field] = { $nin: values };
+        return this;
+    }
+    /**
+     * Add text search filter
+     */
+    search(term, fields) {
+        this._filter.$text = { $search: term };
+        if (fields) {
+            this._filter.$text.$searchFields = fields;
+        }
+        return this;
+    }
+    /**
+     * Expand a reference field (resolve the reference to full document)
+     * @param field Field name to expand. Use 'field[]' syntax for array references
+     */
+    expand(field) {
+        const isArray = field.endsWith('[]');
+        const cleanField = isArray ? field.slice(0, -2) : field;
+        this._expand.push({
+            field: cleanField,
+            isArray
+        });
+        return this;
+    }
+    /**
+     * Set sort order
+     * @param sortConfig Sort configuration object
+     */
+    sort(sortConfig) {
+        this._sort = { ...this._sort, ...sortConfig };
+        return this;
+    }
+    /**
+     * Sort by field ascending
+     */
+    sortAsc(field) {
+        this._sort[field] = 'asc';
+        return this;
+    }
+    /**
+     * Sort by field descending
+     */
+    sortDesc(field) {
+        this._sort[field] = 'desc';
+        return this;
+    }
+    /**
+     * Sort by creation date (newest first)
+     */
+    newest() {
+        this._sort._createdAt = 'desc';
+        return this;
+    }
+    /**
+     * Sort by creation date (oldest first)
+     */
+    oldest() {
+        this._sort._createdAt = 'asc';
+        return this;
+    }
+    /**
+     * Limit number of results
+     */
+    limit(count) {
+        this._limit = count;
+        return this;
+    }
+    /**
+     * Skip first N results
+     */
+    offset(count) {
+        this._offset = count;
+        return this;
+    }
+    /**
+     * Skip first N results (alias for offset)
+     */
+    skip(count) {
+        return this.offset(count);
+    }
+    /**
+     * Select specific fields only
+     */
+    select(...fields) {
+        this._select = fields;
+        return this;
+    }
+    /**
+     * Disable caching for this query
+     */
+    noCache() {
+        this._options.useCache = false;
+        return this;
+    }
+    /**
+     * Add cache-busting timestamp to prevent stale data
+     */
+    fresh() {
+        this._options.noTimestamp = false;
+        this._options.useCache = false;
+        return this;
+    }
+    /**
+     * Execute the query and return results
+     */
+    async fetch() {
+        const result = await this.fetchWithMeta();
+        return result.documents;
+    }
+    /**
+     * Execute the query and return results with metadata
+     */
+    async fetchWithMeta() {
+        // Build query options
+        const options = {};
+        if (Object.keys(this._filter).length > 0) {
+            options.filter = this._filter;
+        }
+        if (Object.keys(this._sort).length > 0) {
+            options.sort = this._sort;
+        }
+        if (this._limit !== undefined) {
+            options.limit = this._limit;
+        }
+        if (this._offset !== undefined) {
+            options.offset = this._offset;
+        }
+        if (this._select) {
+            options.select = this._select;
+        }
+        // Build cache key
+        const cacheKey = this.cache.generateKey(`collections/${this._type}`, {
+            ...options,
+            expand: this._expand.map(e => e.field)
+        });
+        // Check cache
+        if (this._options.useCache) {
+            const cached = this.cache.get(cacheKey);
+            if (cached) {
+                return {
+                    ...cached,
+                    documents: cached.data || []
+                };
+            }
+        }
+        // Build query params
+        const queryParams = new URLSearchParams();
+        if (options.filter) {
+            queryParams.set('filter', JSON.stringify(options.filter));
+        }
+        if (options.sort && Object.keys(options.sort).length > 0) {
+            Object.entries(options.sort).forEach(([field, direction]) => {
+                const dir = direction === -1 || direction === 'desc' ? 'desc' : 'asc';
+                queryParams.append('sort', `${field}.${dir}`);
+            });
+        }
+        if (options.limit) {
+            queryParams.set('limit', options.limit.toString());
+        }
+        if (options.offset) {
+            queryParams.set('offset', options.offset.toString());
+        }
+        if (options.select) {
+            queryParams.set('select', options.select.join(','));
+        }
+        // Add server-side expansion if configured
+        if (this._expand.length > 0) {
+            const expandFields = this._expand.map(e => e.isArray ? `${e.field}[]` : e.field);
+            queryParams.set('expand', expandFields.join(','));
+        }
+        // Add timestamp for fresh queries
+        if (!this._options.noTimestamp && !this._options.useCache) {
+            queryParams.set('_t', Date.now().toString());
+        }
+        // Execute query
+        const endpoint = `/collections/${this._type}${queryParams.toString() ? `?${queryParams.toString()}` : ''}`;
+        const result = await this.http.get(endpoint);
+        // Extract documents from result
+        let documents = result.data || [];
+        // Note: References are now expanded server-side via the expand query param
+        // Client-side expansion is kept as fallback for older API versions
+        if (this._expand.length > 0 && documents.length > 0 && !this.hasExpandedReferences(documents)) {
+            documents = await this.expandReferences(documents);
+        }
+        // Cache result
+        if (this._options.useCache) {
+            this.cache.set(cacheKey, result);
+        }
+        return {
+            ...result,
+            documents
+        };
+    }
+    /**
+     * Get first result or null
+     */
+    async first() {
+        this._limit = 1;
+        const results = await this.fetch();
+        return results[0] || null;
+    }
+    /**
+     * Get count of matching documents
+     */
+    async count() {
+        const queryParams = new URLSearchParams();
+        if (Object.keys(this._filter).length > 0) {
+            queryParams.set('filter', JSON.stringify(this._filter));
+        }
+        const endpoint = `/collections/${this._type}/count${queryParams.toString() ? `?${queryParams.toString()}` : ''}`;
+        const result = await this.http.get(endpoint);
+        return result.count;
+    }
+    /**
+     * Check if any documents match the query
+     */
+    async exists() {
+        const count = await this.count();
+        return count > 0;
+    }
+    /**
+     * Check if references have already been expanded by the server
+     */
+    hasExpandedReferences(documents) {
+        if (documents.length === 0)
+            return false;
+        const doc = documents[0];
+        for (const expandConfig of this._expand) {
+            const fieldValue = this.getNestedValue(doc, expandConfig.field);
+            if (fieldValue) {
+                // If it's an array, check first item
+                if (expandConfig.isArray && Array.isArray(fieldValue) && fieldValue.length > 0) {
+                    const firstItem = fieldValue[0];
+                    // If it has _id, it's been expanded (not just a reference with _ref)
+                    if (firstItem && typeof firstItem === 'object' && '_id' in firstItem) {
+                        return true;
+                    }
+                }
+                else if (typeof fieldValue === 'object' && '_id' in fieldValue && !('_ref' in fieldValue)) {
+                    // Single reference that's been expanded (has _id but no _ref)
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Expand references in documents
+     */
+    async expandReferences(documents) {
+        // Collect all references to fetch
+        const referencesToFetch = new Map();
+        for (const doc of documents) {
+            for (const expandConfig of this._expand) {
+                const fieldValue = this.getNestedValue(doc, expandConfig.field);
+                if (!fieldValue)
+                    continue;
+                if (expandConfig.isArray && Array.isArray(fieldValue)) {
+                    // Array of references
+                    for (const ref of fieldValue) {
+                        if (this.isReference(ref)) {
+                            const type = ref._type || this.inferTypeFromRef(ref._ref);
+                            if (!referencesToFetch.has(type)) {
+                                referencesToFetch.set(type, new Set());
+                            }
+                            referencesToFetch.get(type).add(ref._ref);
+                        }
+                    }
+                }
+                else if (this.isReference(fieldValue)) {
+                    // Single reference
+                    const type = fieldValue._type || this.inferTypeFromRef(fieldValue._ref);
+                    if (!referencesToFetch.has(type)) {
+                        referencesToFetch.set(type, new Set());
+                    }
+                    referencesToFetch.get(type).add(fieldValue._ref);
+                }
+            }
+        }
+        // Fetch all referenced documents in parallel
+        const resolvedRefs = new Map();
+        const fetchPromises = [];
+        for (const [type, ids] of referencesToFetch) {
+            for (const id of ids) {
+                const promise = this.fetchReference(type, id)
+                    .then(doc => {
+                    if (doc) {
+                        resolvedRefs.set(`${type}:${id}`, doc);
+                    }
+                })
+                    .catch(err => {
+                    console.warn(`Failed to resolve reference ${type}/${id}:`, err);
+                });
+                fetchPromises.push(promise);
+            }
+        }
+        await Promise.all(fetchPromises);
+        // Replace references with resolved documents
+        return documents.map(doc => {
+            const expanded = JSON.parse(JSON.stringify(doc));
+            for (const expandConfig of this._expand) {
+                const fieldValue = this.getNestedValue(expanded, expandConfig.field);
+                if (!fieldValue)
+                    continue;
+                if (expandConfig.isArray && Array.isArray(fieldValue)) {
+                    const expandedArray = fieldValue.map((ref) => {
+                        if (this.isReference(ref)) {
+                            const type = ref._type || this.inferTypeFromRef(ref._ref);
+                            const resolved = resolvedRefs.get(`${type}:${ref._ref}`);
+                            return resolved || ref;
+                        }
+                        return ref;
+                    });
+                    this.setNestedValue(expanded, expandConfig.field, expandedArray);
+                }
+                else if (this.isReference(fieldValue)) {
+                    const type = fieldValue._type || this.inferTypeFromRef(fieldValue._ref);
+                    const resolved = resolvedRefs.get(`${type}:${fieldValue._ref}`);
+                    if (resolved) {
+                        this.setNestedValue(expanded, expandConfig.field, resolved);
+                    }
+                }
+            }
+            return expanded;
+        });
+    }
+    /**
+     * Check if a value is a reference object
+     */
+    isReference(value) {
+        return value && typeof value === 'object' && '_ref' in value;
+    }
+    /**
+     * Get a nested value from an object using dot notation path
+     * @param obj The object to traverse
+     * @param path Dot-separated path (e.g., 'documentation.featuredDocument')
+     */
+    getNestedValue(obj, path) {
+        return path.split('.').reduce((current, key) => current?.[key], obj);
+    }
+    /**
+     * Set a nested value in an object using dot notation path
+     * @param obj The object to modify
+     * @param path Dot-separated path (e.g., 'documentation.featuredDocument')
+     * @param value The value to set
+     */
+    setNestedValue(obj, path, value) {
+        const keys = path.split('.');
+        const lastKey = keys.pop();
+        const target = keys.reduce((current, key) => (current[key] ?? (current[key] = {})), obj);
+        target[lastKey] = value;
+    }
+    /**
+     * Infer type from reference ID (e.g., 'category-abc123' -> 'category')
+     */
+    inferTypeFromRef(ref) {
+        // Try to extract type from ref format like 'category-abc123'
+        const match = ref.match(/^([a-z-]+)-/);
+        return match ? match[1] : 'document';
+    }
+    /**
+     * Extract document from API response
+     */
+    extractDocument(result) {
+        if (!result)
+            return null;
+        // Handle direct document (has _id at top level)
+        if (result._id) {
+            return result;
+        }
+        // Handle { data: { ... } } wrapper
+        if (result.data && typeof result.data === 'object' && !Array.isArray(result.data)) {
+            return this.extractDocument(result.data);
+        }
+        // Handle { data: [...] } wrapper (take first item)
+        if (result.data && Array.isArray(result.data)) {
+            return result.data[0] || null;
+        }
+        // Handle { [collectionName]: { _id: "...", ... } } wrapper (e.g., { document: { _id: "..." } })
+        // This occurs when the API returns the document wrapped in a property named after the collection
+        const keys = Object.keys(result);
+        if (keys.length === 1) {
+            const wrappedValue = result[keys[0]];
+            if (wrappedValue && typeof wrappedValue === 'object' && wrappedValue._id) {
+                return wrappedValue;
+            }
+        }
+        // Fallback: return as-is
+        return result;
+    }
+    /**
+     * Fetch a single referenced document
+     */
+    async fetchReference(type, id) {
+        try {
+            const result = await this.http.get(`/collections/${type}/${id}`);
+            return this.extractDocument(result);
+        }
+        catch (error) {
+            // Try without type prefix in ID
+            if (id.startsWith(`${type}-`)) {
+                const cleanId = id.replace(`${type}-`, '');
+                try {
+                    const result = await this.http.get(`/collections/${type}/${cleanId}`);
+                    return this.extractDocument(result);
+                }
+                catch {
+                    return null;
+                }
+            }
+            return null;
+        }
+    }
+}
+/**
+ * Singleton query builder for fetching a single document by type
+ */
+export class SingletonBuilder {
+    constructor(http, cache, _type, _id) {
+        this.http = http;
+        this.cache = cache;
+        this._type = _type;
+        this._id = _id;
+        this._expand = [];
+        this._options = { useCache: false };
+    }
+    /**
+     * Expand a reference field
+     */
+    expand(field) {
+        const isArray = field.endsWith('[]');
+        const cleanField = isArray ? field.slice(0, -2) : field;
+        this._expand.push({
+            field: cleanField,
+            isArray
+        });
+        return this;
+    }
+    /**
+     * Disable caching
+     */
+    noCache() {
+        this._options.useCache = false;
+        return this;
+    }
+    /**
+     * Fetch fresh data with cache busting
+     */
+    fresh() {
+        this._options.useCache = false;
+        return this;
+    }
+    /**
+     * Execute and return the singleton document
+     */
+    async fetch() {
+        const queryParams = new URLSearchParams();
+        if (!this._options.useCache) {
+            queryParams.set('_t', Date.now().toString());
+        }
+        // Add server-side expansion if configured
+        if (this._expand.length > 0) {
+            const expandFields = this._expand.map(e => e.isArray ? `${e.field}[]` : e.field);
+            queryParams.set('expand', expandFields.join(','));
+        }
+        // For singletons, try specific ID first, then fall back to collection query
+        let endpoint;
+        if (this._id) {
+            endpoint = `/collections/${this._type}/${this._id}${queryParams.toString() ? `?${queryParams.toString()}` : ''}`;
+        }
+        else {
+            // Query the collection and get first result
+            queryParams.set('limit', '1');
+            endpoint = `/collections/${this._type}${queryParams.toString() ? `?${queryParams.toString()}` : ''}`;
+        }
+        try {
+            const result = await this.http.get(endpoint);
+            // Handle collection response vs single document
+            let doc = null;
+            if (result.data && Array.isArray(result.data)) {
+                doc = result.data[0] || null;
+            }
+            else if (result.data) {
+                doc = result.data;
+            }
+            else if (result._id) {
+                doc = result;
+            }
+            // Check if published (for singleton pages)
+            if (doc && doc._status && doc._status !== 'published') {
+                return null;
+            }
+            // Note: References are now expanded server-side via the expand query param
+            // Client-side expansion is kept as fallback for older API versions
+            if (doc && this._expand.length > 0 && !this.hasExpandedReferences(doc)) {
+                doc = await this.expandReferences(doc);
+            }
+            return doc;
+        }
+        catch (error) {
+            console.warn(`Failed to fetch singleton ${this._type}:`, error);
+            return null;
+        }
+    }
+    /**
+     * Check if references have already been expanded by the server
+     */
+    hasExpandedReferences(doc) {
+        for (const expandConfig of this._expand) {
+            const fieldValue = this.getNestedValue(doc, expandConfig.field);
+            if (fieldValue) {
+                // If it's an array, check first item
+                if (expandConfig.isArray && Array.isArray(fieldValue) && fieldValue.length > 0) {
+                    const firstItem = fieldValue[0];
+                    // If it has _id, it's been expanded (not just a reference with _ref)
+                    if (firstItem && typeof firstItem === 'object' && '_id' in firstItem) {
+                        return true;
+                    }
+                }
+                else if (typeof fieldValue === 'object' && '_id' in fieldValue && !('_ref' in fieldValue)) {
+                    // Single reference that's been expanded (has _id but no _ref)
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Expand references in a single document
+     */
+    async expandReferences(doc) {
+        const expanded = JSON.parse(JSON.stringify(doc));
+        for (const expandConfig of this._expand) {
+            const fieldValue = this.getNestedValue(expanded, expandConfig.field);
+            if (!fieldValue)
+                continue;
+            if (expandConfig.isArray && Array.isArray(fieldValue)) {
+                const expandedArray = await Promise.all(fieldValue.map(async (ref) => {
+                    if (this.isReference(ref)) {
+                        const type = ref._type || this.inferTypeFromRef(ref._ref);
+                        return await this.fetchReference(type, ref._ref) || ref;
+                    }
+                    return ref;
+                }));
+                this.setNestedValue(expanded, expandConfig.field, expandedArray);
+            }
+            else if (this.isReference(fieldValue)) {
+                const type = fieldValue._type || this.inferTypeFromRef(fieldValue._ref);
+                const resolved = await this.fetchReference(type, fieldValue._ref);
+                if (resolved) {
+                    this.setNestedValue(expanded, expandConfig.field, resolved);
+                }
+            }
+        }
+        return expanded;
+    }
+    isReference(value) {
+        return value && typeof value === 'object' && '_ref' in value;
+    }
+    /**
+     * Get a nested value from an object using dot notation path
+     * @param obj The object to traverse
+     * @param path Dot-separated path (e.g., 'documentation.featuredDocument')
+     */
+    getNestedValue(obj, path) {
+        return path.split('.').reduce((current, key) => current?.[key], obj);
+    }
+    /**
+     * Set a nested value in an object using dot notation path
+     * @param obj The object to modify
+     * @param path Dot-separated path (e.g., 'documentation.featuredDocument')
+     * @param value The value to set
+     */
+    setNestedValue(obj, path, value) {
+        const keys = path.split('.');
+        const lastKey = keys.pop();
+        const target = keys.reduce((current, key) => (current[key] ?? (current[key] = {})), obj);
+        target[lastKey] = value;
+    }
+    inferTypeFromRef(ref) {
+        const match = ref.match(/^([a-z-]+)-/);
+        return match ? match[1] : 'document';
+    }
+    /**
+     * Extract document from API response
+     */
+    extractDocument(result) {
+        if (!result)
+            return null;
+        // Handle direct document (has _id at top level)
+        if (result._id) {
+            return result;
+        }
+        // Handle { data: { ... } } wrapper
+        if (result.data && typeof result.data === 'object' && !Array.isArray(result.data)) {
+            return this.extractDocument(result.data);
+        }
+        // Handle { data: [...] } wrapper (take first item)
+        if (result.data && Array.isArray(result.data)) {
+            return result.data[0] || null;
+        }
+        // Handle { [collectionName]: { _id: "...", ... } } wrapper (e.g., { document: { _id: "..." } })
+        // This occurs when the API returns the document wrapped in a property named after the collection
+        const keys = Object.keys(result);
+        if (keys.length === 1) {
+            const wrappedValue = result[keys[0]];
+            if (wrappedValue && typeof wrappedValue === 'object' && wrappedValue._id) {
+                return wrappedValue;
+            }
+        }
+        // Fallback: return as-is
+        return result;
+    }
+    async fetchReference(type, id) {
+        try {
+            const result = await this.http.get(`/collections/${type}/${id}`);
+            return this.extractDocument(result);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=builder.js.map