hlquery-node-client 1.0.0

package/utils/PDFParser.js

@@ -0,0 +1,196 @@
+/**
+ * hlquery Node.js Client - Optional PDF parsing helper
+ *
+ * Copyright (C) 2021-2026, Carlos F. Ferry <carlos.ferry@gmail.com>
+ *
+ * This file is part of hlquery, released under the BSD License version 3.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { ValidationException } = require('../lib/Exceptions');
+
+class PDFParser {
+    /**
+     * Parse a PDF file from disk.
+     *
+     * @param {string} filePath
+     * @param {object} options
+     * @returns {Promise<object>}
+     */
+    static async parseFile(filePath, options = {}) {
+        this.validateFilePath(filePath);
+
+        const resolvedPath = path.resolve(filePath);
+        const stat = fs.statSync(resolvedPath);
+
+        if (!stat.isFile()) {
+            throw new ValidationException(`PDF path is not a file: ${resolvedPath}`);
+        }
+
+        const pdfParse = this.loadPDFParse();
+        const buffer = fs.readFileSync(resolvedPath);
+        const parsed = await pdfParse(buffer);
+        const metadata = parsed && parsed.metadata && typeof parsed.metadata === 'object'
+            ? parsed.metadata
+            : {};
+
+        const content = this.normalizeText(parsed && parsed.text ? parsed.text : '', options);
+        const title = this.resolveTitle(resolvedPath, metadata, options);
+        const fileName = path.basename(resolvedPath);
+
+        return {
+            filePath: resolvedPath,
+            fileName: fileName,
+            title: title,
+            content: content,
+            pageCount: parsed && typeof parsed.numpages === 'number' ? parsed.numpages : null,
+            info: parsed && parsed.info ? parsed.info : {},
+            metadata: metadata,
+            version: parsed && parsed.version ? parsed.version : null,
+            sizeBytes: stat.size
+        };
+    }
+
+    /**
+     * Build a standard hlquery document from parsed PDF data.
+     *
+     * @param {object} parsed
+     * @param {object} options
+     * @returns {object}
+     */
+    static buildDocumentFromParsedPDF(parsed, options = {}) {
+        const contentField = options.contentField || 'content';
+        const titleField = options.titleField || 'title';
+        const document = Object.assign({}, options.document || {});
+
+        document.id = options.id || document.id || this.generateDocumentId(parsed.fileName);
+        document[titleField] = options.title || document[titleField] || parsed.title;
+        document[contentField] = parsed.content;
+
+        if (options.includeMetadata !== false) {
+            document.file_name = parsed.fileName;
+            document.file_path = parsed.filePath;
+            document.mime_type = 'application/pdf';
+
+            if (parsed.pageCount !== null) {
+                document.page_count = String(parsed.pageCount);
+            }
+
+            if (parsed.sizeBytes !== null) {
+                document.file_size_bytes = String(parsed.sizeBytes);
+            }
+
+            this.attachMetadata(document, parsed.info, 'pdf_info', options);
+            this.attachMetadata(document, parsed.metadata, 'pdf_meta', options);
+        }
+
+        return document;
+    }
+
+    static attachMetadata(document, metadata, prefix, options = {}) {
+        if (!metadata || typeof metadata !== 'object') {
+            return;
+        }
+
+        const fieldPrefix = options.metadataPrefix || prefix;
+
+        for (const [key, value] of Object.entries(metadata)) {
+            if (value === null || value === undefined) {
+                continue;
+            }
+
+            const normalizedKey = this.normalizeFieldName(`${fieldPrefix}_${key}`);
+            const normalizedValue = this.normalizeMetadataValue(value, options);
+
+            if (normalizedKey && normalizedValue !== '') {
+                document[normalizedKey] = normalizedValue;
+            }
+        }
+    }
+
+    static normalizeMetadataValue(value, options = {}) {
+        if (typeof value === 'string') {
+            return this.normalizeText(value, options);
+        }
+
+        if (typeof value === 'number' || typeof value === 'boolean') {
+            return String(value);
+        }
+
+        return this.normalizeText(JSON.stringify(value), options);
+    }
+
+    static normalizeFieldName(name) {
+        return String(name)
+            .trim()
+            .toLowerCase()
+            .replace(/[^a-z0-9_]+/g, '_')
+            .replace(/^_+|_+$/g, '')
+            .slice(0, 64);
+    }
+
+    static normalizeText(text, options = {}) {
+        let output = String(text || '');
+
+        output = output.replace(/\r\n/g, '\n');
+
+        if (options.stripNullBytes !== false) {
+            output = output.replace(/\0/g, '');
+        }
+
+        if (options.sanitizeCommas !== false) {
+            output = output.replace(/,/g, ' ');
+        }
+
+        if (options.collapseWhitespace !== false) {
+            output = output.replace(/[ \t]+/g, ' ');
+            output = output.replace(/\n{3,}/g, '\n\n');
+        }
+
+        return output.trim();
+    }
+
+    static resolveTitle(filePath, metadata, options = {}) {
+        if (options.title) {
+            return this.normalizeText(options.title, options);
+        }
+
+        if (metadata && typeof metadata.Title === 'string' && metadata.Title.trim() !== '') {
+            return this.normalizeText(metadata.Title, options);
+        }
+
+        return this.normalizeText(path.basename(filePath, path.extname(filePath)), options);
+    }
+
+    static generateDocumentId(fileName) {
+        const stem = path.basename(fileName, path.extname(fileName))
+            .toLowerCase()
+            .replace(/[^a-z0-9._-]+/g, '_')
+            .replace(/^_+|_+$/g, '')
+            .slice(0, 40);
+        const suffix = crypto.randomBytes(4).toString('hex');
+
+        return `${stem || 'pdf'}_${suffix}`;
+    }
+
+    static validateFilePath(filePath) {
+        if (!filePath || typeof filePath !== 'string') {
+            throw new ValidationException('PDF file path must be a non-empty string');
+        }
+    }
+
+    static loadPDFParse() {
+        try {
+            return require('pdf-parse');
+        } catch (error) {
+            throw new ValidationException(
+                'PDF parsing requires the optional dependency `pdf-parse`. ' +
+                'Install it in etc/api/node with `npm install pdf-parse`.'
+            );
+        }
+    }
+}
+
+module.exports = PDFParser;

package/utils/Validator.js

@@ -0,0 +1,143 @@
+/**
+ * hlquery Node.js Client - Input Validation
+ * 
+ * Copyright (C) 2021-2026, Carlos F. Ferry <carlos.ferry@gmail.com>
+ * 
+ * This file is part of hlquery, released under the BSD License version 3.
+ */
+
+const { ValidationException } = require('../lib/Exceptions');
+
+/**
+ * Input validation utilities
+ */
+class Validator {
+    /**
+     * Validate collection name
+     */
+    static validateCollectionName(name) {
+        if (!name || typeof name !== 'string' || name.trim() === '') {
+            throw new ValidationException('Collection name must be a non-empty string');
+        }
+        
+        // Check name length (matches server validation: 1-64 characters)
+        if (name.length > 64) {
+            throw new ValidationException('Collection name must be between 1 and 64 characters');
+        }
+        
+        // Collection names should be URL-safe
+        if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+            throw new ValidationException(
+                'Collection name contains invalid characters. ' +
+                'Use only letters, numbers, underscores, and hyphens'
+            );
+        }
+        
+        // Check if name starts with letter or underscore (matches server validation)
+        const firstChar = name[0];
+        if (!/[a-zA-Z]/.test(firstChar) && firstChar !== '_') {
+            throw new ValidationException('Collection name must start with a letter or underscore');
+        }
+    }
+    
+    /**
+     * Validate document ID
+     */
+    static validateDocumentId(id) {
+        if (!id || (typeof id !== 'string' && typeof id !== 'number')) {
+            throw new ValidationException('Document ID must be a non-empty string or number');
+        }
+        
+        // Convert to string for validation
+        const idStr = String(id);
+        
+        // Check name length (matches server validation: 1-64 characters)
+        if (idStr.length > 64) {
+            throw new ValidationException('Document ID must be between 1 and 64 characters');
+        }
+        
+        // Document IDs should be URL-safe: alphanumeric, underscores, and hyphens only
+        if (!/^[a-zA-Z0-9_-]+$/.test(idStr)) {
+            throw new ValidationException(
+                'Document ID contains invalid characters. ' +
+                'Use only letters, numbers, underscores, and hyphens'
+            );
+        }
+    }
+    
+    /**
+     * Validate pagination parameters
+     */
+    static validatePagination(offset, limit) {
+        if (offset !== undefined && (typeof offset !== 'number' || offset < 0)) {
+            throw new ValidationException('Offset must be a non-negative number');
+        }
+        if (limit !== undefined && (typeof limit !== 'number' || limit < 1)) {
+            throw new ValidationException('Limit must be a positive number');
+        }
+    }
+    
+    /**
+     * Validate search parameters
+     */
+    static validateSearchParams(params) {
+        if (params && typeof params !== 'object') {
+            throw new ValidationException('Search parameters must be an object');
+        }
+        
+        if (params) {
+            if (params.offset !== undefined && (typeof params.offset !== 'number' || params.offset < 0)) {
+                throw new ValidationException('Offset must be a non-negative number');
+            }
+            if (params.limit !== undefined && (typeof params.limit !== 'number' || params.limit < 1)) {
+                throw new ValidationException('Limit must be a positive number');
+            }
+            if (params.from !== undefined && (typeof params.from !== 'number' || params.from < 0)) {
+                throw new ValidationException('From must be a non-negative number');
+            }
+            if (params.size !== undefined && (typeof params.size !== 'number' || params.size < 1)) {
+                throw new ValidationException('Size must be a positive number');
+            }
+        }
+    }
+    
+    /**
+     * Validate document field values for invalid characters
+     * Commas are not allowed in string field values as they're reserved for internal parsing
+     * 
+     * @param {object} document - Document object to validate
+     * @throws {ValidationException} If document contains invalid characters
+     */
+    static validateDocumentFields(document) {
+        if (!document || typeof document !== 'object' || Array.isArray(document)) {
+            return; // Skip validation for non-objects or arrays (will be validated per-item)
+        }
+        
+        for (const [key, value] of Object.entries(document)) {
+            // Skip the 'id' field as it has its own validation
+            if (key === 'id') continue;
+            
+            // Check string values for commas
+            if (typeof value === 'string' && value.includes(',')) {
+                throw new ValidationException(
+                    `Field '${key}' contains invalid character: comma (`,`). ` +
+                    `Commas are not allowed in field values. Use underscores (_) or spaces instead, or use arrays for multiple values.`
+                );
+            }
+            
+            // Check array values - ensure they don't contain strings with commas
+            if (Array.isArray(value)) {
+                for (const item of value) {
+                    if (typeof item === 'string' && item.includes(',')) {
+                        throw new ValidationException(
+                            `Field '${key}' contains invalid character: comma (`,`). ` +
+                            `Array items cannot contain commas. Use underscores (_) or spaces instead.`
+                        );
+                    }
+                }
+            }
+        }
+    }
+}
+
+module.exports = Validator;

package/utils/ranker.js

@@ -0,0 +1,51 @@
+/**
+ * hlquery Node.js Client - Ranking Helpers
+ */
+
+const DEFAULT_WEIGHTS = {
+    popularity_log: 1.15,
+    hit_log: 0.95,
+    popularity_sqrt: 0.25,
+    hit_log_sqrt: 0.15,
+};
+
+function computeRankSignal(popularity, hitLog, weights = {}) {
+    const w = { ...DEFAULT_WEIGHTS };
+
+    for (const key of Object.keys(weights)) {
+        if (Object.prototype.hasOwnProperty.call(w, key) && typeof weights[key] === 'number') {
+            w[key] = weights[key];
+        }
+    }
+
+    return (
+        Math.log(popularity + 1) * w.popularity_log
+        + Math.log(hitLog + 1) * w.hit_log
+        + Math.sqrt(popularity) * w.popularity_sqrt
+        + Math.sqrt(hitLog) * w.hit_log_sqrt
+    );
+}
+
+function attachRankSort(params, field = 'rank_signal', direction = 'desc') {
+    if (!params || typeof params !== 'object') {
+        return;
+    }
+
+    direction = direction.toLowerCase();
+    if (direction !== 'asc' && direction !== 'desc') {
+        direction = 'desc';
+    }
+
+    const sortInstruction = `${field}:${direction}`;
+
+    if (typeof params.sort_by === 'string' && params.sort_by.trim()) {
+        params.sort_by = `${params.sort_by},${sortInstruction}`;
+    } else {
+        params.sort_by = sortInstruction;
+    }
+}
+
+module.exports = {
+    computeRankSignal,
+    attachRankSort
+};