hlquery-node-client 1.0.5 → 1.0.7

package/lib/Documents.js

@@ -18,6 +18,13 @@ class Documents {
     constructor(request) {
         this.request = request;
     }
+
+    _responseFromRequestError(error) {
+        if (error && error.response) {
+            return error.response;
+        }
+        throw error;
+    }
     
     /**
      * List documents in a collection
@@ -52,6 +59,20 @@ class Documents {
         
         return await this.request.execute('GET', `/collections/${encodeURIComponent(collectionName)}/documents/${encodeURIComponent(documentId)}`);
     }
+
+    /**
+     * Get alternate contextual phrases for a document.
+     *
+     * @param {string} collectionName
+     * @param {string} documentId
+     * @returns {Promise<Response>}
+     */
+    async context(collectionName, documentId) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentId(documentId);
+
+        return await this.request.execute('GET', `/collections/${encodeURIComponent(collectionName)}/documents/${encodeURIComponent(documentId)}/context`);
+    }
     
     /**
      * Add a document
@@ -177,14 +198,24 @@ class Documents {
         }
         
         // Server expects {documents: [...]} format; fall back to per-doc inserts if bulk route is unavailable.
-        const bulkResponse = await this.request.execute('POST', `/collections/${encodeURIComponent(collectionName)}/documents/import`, {
-            documents: documents
-        });
+        let bulkResponse;
+        try {
+            bulkResponse = await this.request.execute('POST', `/collections/${encodeURIComponent(collectionName)}/documents/import`, {
+                documents: documents
+            });
+        } catch (error) {
+            bulkResponse = this._responseFromRequestError(error);
+        }
 
         if (bulkResponse && bulkResponse.getStatusCode && bulkResponse.getStatusCode() === 404) {
             let inserted = 0;
             for (const doc of documents) {
-                const response = await this.request.execute('POST', `/collections/${encodeURIComponent(collectionName)}/documents`, doc);
+                let response;
+                try {
+                    response = await this.request.execute('POST', `/collections/${encodeURIComponent(collectionName)}/documents`, doc);
+                } catch (error) {
+                    response = this._responseFromRequestError(error);
+                }
                 const status = response.getStatusCode();
                 if (status !== 201) {
                     return response;
@@ -215,7 +246,12 @@ class Documents {
             throw new Error('Source and target document ids must differ');
         }
 
-        const targetCheck = await this.get(collectionName, targetId);
+        let targetCheck;
+        try {
+            targetCheck = await this.get(collectionName, targetId);
+        } catch (error) {
+            targetCheck = this._responseFromRequestError(error);
+        }
         if (targetCheck.getStatusCode() === 200) {
             return targetCheck;
         }
@@ -223,7 +259,12 @@ class Documents {
             return targetCheck;
         }
 
-        const sourceResponse = await this.get(collectionName, sourceId);
+        let sourceResponse;
+        try {
+            sourceResponse = await this.get(collectionName, sourceId);
+        } catch (error) {
+            sourceResponse = this._responseFromRequestError(error);
+        }
         if (sourceResponse.getStatusCode() !== 200) {
             return sourceResponse;
         }
@@ -302,6 +343,57 @@ class Documents {
             queryParams
         );
     }
+
+    /**
+     * Request query suggestions for a collection.
+     *
+     * @param {string} collectionName
+     * @param {object} params
+     * @returns {Promise<Response>}
+     */
+    async maybe(collectionName, params = {}) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateSearchParams(params);
+
+        const method = params.body ? 'POST' : 'GET';
+        const body = params.body || (method === 'POST' ? params : null);
+        const queryParams = method === 'GET' ? params : {};
+
+        return await this.request.execute(
+            method,
+            `/collections/${encodeURIComponent(collectionName)}/documents/maybe`,
+            body,
+            queryParams
+        );
+    }
+
+    /**
+     * Update documents matching a query.
+     *
+     * @param {string} collectionName
+     * @param {object} body
+     * @returns {Promise<Response>}
+     */
+    async updateByQuery(collectionName, body = {}) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentFields(body);
+
+        return await this.request.execute('POST', `/collections/${encodeURIComponent(collectionName)}/documents/_update_by_query`, body);
+    }
+
+    /**
+     * Delete documents matching a query.
+     *
+     * @param {string} collectionName
+     * @param {object} body
+     * @returns {Promise<Response>}
+     */
+    async deleteByQuery(collectionName, body = {}) {
+        Validator.validateCollectionName(collectionName);
+        Validator.validateDocumentFields(body);
+
+        return await this.request.execute('POST', `/collections/${encodeURIComponent(collectionName)}/documents/_delete_by_query`, body);
+    }
     
     /**
      * Delete documents by filter

package/lib/Exceptions.js

@@ -10,9 +10,12 @@
  * Base exception class for hlquery client
  */
 class HlqueryException extends Error {
-    constructor(message) {
+    constructor(message, options = {}) {
         super(message);
         this.name = 'HlqueryException';
+        if (options.cause) {
+            this.cause = options.cause;
+        }
         Error.captureStackTrace(this, this.constructor);
     }
 }
@@ -31,11 +34,16 @@ class AuthenticationException extends HlqueryException {
  * Exception thrown when a request fails
  */
 class RequestException extends HlqueryException {
-    constructor(message, statusCode = 0, responseBody = null) {
-        super(message);
+    constructor(message, statusCode = 0, responseBody = null, options = {}) {
+        super(message, options);
         this.name = 'RequestException';
         this.statusCode = statusCode;
         this.responseBody = responseBody;
+        this.response = options.response || null;
+        this.headers = options.headers || {};
+        this.rawBody = options.rawBody || null;
+        this.retryable = Boolean(options.retryable);
+        this.code = options.code || null;
     }
 }
 

package/lib/Modules.js

@@ -0,0 +1,64 @@
+/**
+ * hlquery Node.js Client - Runtime Modules API
+ *
+ * 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 { ModuleRouteCommand, cleanRoute } = require('./Route');
+
+function requireNonEmptyString(value, label) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`${label} must be a non-empty string`);
+    }
+}
+
+/**
+ * Runtime module discovery and dynamic route calls.
+ */
+class Modules {
+    constructor(request) {
+        this.request = request;
+    }
+
+    list() {
+        return this.request.execute('GET', '/modules');
+    }
+
+    load(name) {
+        requireNonEmptyString(name, 'Module name');
+        return this.request.execute('POST', `/loadmodule/${encodeURIComponent(name)}`);
+    }
+
+    unload(name) {
+        requireNonEmptyString(name, 'Module name');
+        return this.request.execute('POST', `/unloadmodule/${encodeURIComponent(name)}`);
+    }
+
+    syntax(name, queryParams = {}) {
+        return this.module(name).syntax(queryParams);
+    }
+
+    module(name) {
+        return new ModuleRouteCommand(this.request, name);
+    }
+
+    route(name, route = '') {
+        return this.module(name).route(route);
+    }
+
+    call(name, route = '', method = 'GET', body = null, queryParams = {}, options = {}) {
+        requireNonEmptyString(name, 'Module name');
+        requireNonEmptyString(method, 'HTTP method');
+
+        const suffix = cleanRoute(route);
+        const path = suffix
+            ? `/modules/${encodeURIComponent(name)}/${suffix}`
+            : `/modules/${encodeURIComponent(name)}`;
+
+        return this.request.execute(method.toUpperCase(), path, body, queryParams, options);
+    }
+}
+
+module.exports = Modules;

package/lib/Request.js

@@ -16,11 +16,26 @@ const Response = require('./Response');
  * HTTP request handler
  */
 class Request {
-    constructor(baseUrl, timeout = 30000, authToken = null, authMethod = 'bearer') {
-        this.baseUrl = baseUrl.replace(/\/$/, '');
+    constructor(baseUrl, timeout = 30000, authToken = null, authMethod = 'bearer', options = {}) {
+        if (timeout && typeof timeout === 'object') {
+            options = timeout;
+            timeout = options.timeout || 30000;
+            authToken = options.token || null;
+            authMethod = options.auth_method || options.authMethod || 'bearer';
+        }
+
+        this.baseUrl = baseUrl.replace(/\/+$/, '');
         this.timeout = timeout;
         this.authToken = authToken;
         this.authMethod = authMethod;
+        this.agent = options.agent || null;
+        this.httpAgent = options.http_agent || options.httpAgent || null;
+        this.httpsAgent = options.https_agent || options.httpsAgent || null;
+        this.defaultHeaders = options.headers || {};
+        this.maxResponseBytes = options.max_response_bytes || options.maxResponseBytes || 0;
+        this.throwOnError = Boolean(options.throw_on_error || options.throwOnError);
+        this.queryArrayFormat = options.query_array_format || options.queryArrayFormat || 'comma';
+        this.signal = options.signal || null;
     }
     
     setAuthToken(token, method = 'bearer') {
@@ -42,8 +57,28 @@ class Request {
      * @returns {Promise<Response>}
      * @throws {RequestException}
      */
-    async execute(method, path, body = null, queryParams = {}) {
-        const url = new URL(this.baseUrl + path);
+    async execute(method, path, body = null, queryParams = {}, requestOptions = {}) {
+        const baseUrl = new URL(`${this.baseUrl}/`);
+        const url = new URL(path, baseUrl);
+        if (url.origin !== baseUrl.origin) {
+            throw new RequestException('Request URL must use the configured server origin', 0, null, {
+                code: 'CROSS_ORIGIN_REQUEST',
+                retryable: false
+            });
+        }
+        const signal = requestOptions.signal || this.signal;
+        const maxResponseBytes = requestOptions.max_response_bytes || requestOptions.maxResponseBytes || this.maxResponseBytes;
+        const throwOnError = requestOptions.throw_on_error !== undefined
+            ? requestOptions.throw_on_error
+            : (requestOptions.throwOnError !== undefined ? requestOptions.throwOnError : this.throwOnError);
+        const queryArrayFormat = requestOptions.query_array_format || requestOptions.queryArrayFormat || this.queryArrayFormat;
+
+        if (signal && signal.aborted) {
+            throw new RequestException('Request aborted', 0, null, {
+                code: 'ABORT_ERR',
+                retryable: false
+            });
+        }
         
         // Add query parameters
         Object.keys(queryParams).forEach(key => {
@@ -53,7 +88,11 @@ class Request {
             }
 
             if (Array.isArray(value)) {
-                url.searchParams.append(key, value.join(','));
+                if (queryArrayFormat === 'repeat' || queryArrayFormat === 'repeated') {
+                    value.forEach(item => url.searchParams.append(key, item));
+                } else {
+                    url.searchParams.append(key, value.join(','));
+                }
                 return;
             }
 
@@ -66,7 +105,9 @@ class Request {
         });
         
         const headers = {
-            'Accept': 'application/json'
+            'Accept': 'application/json',
+            ...this.defaultHeaders,
+            ...(requestOptions.headers || {})
         };
         
         // Prepare body string if present
@@ -89,32 +130,112 @@ class Request {
         const options = {
             method: method,
             headers: headers,
-            timeout: this.timeout
+            timeout: requestOptions.timeout || this.timeout
         };
         
         const client = url.protocol === 'https:' ? https : http;
+        const agent = this.agent || (url.protocol === 'https:' ? this.httpsAgent : this.httpAgent);
+        if (agent) {
+            options.agent = agent;
+        }
         
         return new Promise((resolve, reject) => {
-            const req = client.request(url, options, (res) => {
+            let settled = false;
+            let req = null;
+            const rejectOnce = (error) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                if (signal && abortHandler && typeof signal.removeEventListener === 'function') {
+                    signal.removeEventListener('abort', abortHandler);
+                } else if (signal && abortHandler && typeof signal.removeListener === 'function') {
+                    signal.removeListener('abort', abortHandler);
+                }
+                reject(error);
+            };
+            const resolveOnce = (response) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                if (signal && abortHandler && typeof signal.removeEventListener === 'function') {
+                    signal.removeEventListener('abort', abortHandler);
+                } else if (signal && abortHandler && typeof signal.removeListener === 'function') {
+                    signal.removeListener('abort', abortHandler);
+                }
+                resolve(response);
+            };
+            const abortHandler = () => {
+                if (req) {
+                    req.destroy();
+                }
+                rejectOnce(new RequestException('Request aborted', 0, null, {
+                    code: 'ABORT_ERR',
+                    retryable: false
+                }));
+            };
+
+            if (signal && typeof signal.addEventListener === 'function') {
+                signal.addEventListener('abort', abortHandler, { once: true });
+            } else if (signal && typeof signal.once === 'function') {
+                signal.once('abort', abortHandler);
+            }
+
+            req = client.request(url, options, (res) => {
                 const responseHeaders = {};
                 Object.keys(res.headers).forEach(key => {
                     responseHeaders[key.toLowerCase()] = res.headers[key];
                 });
                 
-                let data = '';
+                const chunks = [];
+                let receivedBytes = 0;
                 
                 res.on('data', (chunk) => {
-                    data += chunk;
+                    receivedBytes += chunk.length;
+                    if (maxResponseBytes > 0 && receivedBytes > maxResponseBytes) {
+                        res.destroy();
+                        rejectOnce(new RequestException(
+                            `Response exceeded maximum size of ${maxResponseBytes} bytes`,
+                            res.statusCode,
+                            null,
+                            {
+                                headers: responseHeaders,
+                                retryable: false,
+                                code: 'MAX_RESPONSE_BYTES'
+                            }
+                        ));
+                        return;
+                    }
+                    chunks.push(chunk);
                 });
                 
                 res.on('end', () => {
+                    if (settled) {
+                        return;
+                    }
+                    const rawBuffer = Buffer.concat(chunks);
+                    const data = rawBuffer.toString('utf8');
                     let decoded;
+                    let parsed = true;
                     try {
                         decoded = data ? JSON.parse(data) : null;
                     } catch (e) {
                         // If JSON parsing fails, return raw response
                         decoded = data;
+                        parsed = false;
                     }
+
+                    const response = new Response(res.statusCode, decoded, responseHeaders, {
+                        statusMessage: res.statusMessage || '',
+                        rawBody: rawBuffer,
+                        parsed: parsed,
+                        request: {
+                            method: method,
+                            url: url.toString(),
+                            path: path
+                        }
+                    });
                     
                     // Check for demo mode errors
                     if (res.statusCode === 403 && decoded && typeof decoded === 'object') {
@@ -122,30 +243,51 @@ class Request {
                         if (errorMsg.includes('Demo mode is enabled') || 
                             errorMsg.includes('Operation not allowed') ||
                             errorMsg.includes('Write operations are not allowed')) {
-                            return reject(new DemoModeException(
+                            return rejectOnce(new DemoModeException(
                                 `Demo mode is enabled on the server. Write operations are blocked. Only search and read operations are permitted. Server message: ${decoded.message || decoded.error}`
                             ));
                         }
                         // Check if server rejected token because auth is disabled
                         if (errorMsg.includes('Authentication is disabled') || 
                             errorMsg.includes('Tokens are not accepted when authentication is disabled')) {
-                            return reject(new AuthenticationException(
+                            return rejectOnce(new AuthenticationException(
                                 `Authentication is disabled on the server. Remove the token from your client configuration. Server message: ${decoded.message || decoded.error}`
                             ));
                         }
                     }
+
+                    if (throwOnError && response.isError()) {
+                        const errorMessage = response.getError() ||
+                            `${res.statusCode} ${res.statusMessage || 'HTTP error'}`;
+                        return rejectOnce(new RequestException(errorMessage, res.statusCode, decoded, {
+                            response: response,
+                            headers: responseHeaders,
+                            rawBody: rawBuffer,
+                            retryable: res.statusCode >= 500
+                        }));
+                    }
                     
-                    resolve(new Response(res.statusCode, decoded, responseHeaders));
+                    resolveOnce(response);
                 });
             });
             
             req.on('error', (error) => {
-                reject(new RequestException(`Request failed: ${error.message}`, 0));
+                if (settled) {
+                    return;
+                }
+                rejectOnce(new RequestException(`Request failed: ${error.message}`, 0, null, {
+                    cause: error,
+                    retryable: true,
+                    code: error.code || null
+                }));
             });
             
             req.on('timeout', () => {
                 req.destroy();
-                reject(new RequestException('Request timeout', 0));
+                rejectOnce(new RequestException('Request timeout', 0, null, {
+                    retryable: true,
+                    code: 'ETIMEDOUT'
+                }));
             });
             
             if (bodyStr !== null) {

package/lib/Response.js

@@ -10,10 +10,15 @@
  * Response wrapper for API responses
  */
 class Response {
-    constructor(statusCode, body, headers = {}) {
+    constructor(statusCode, body, headers = {}, options = {}) {
         this.statusCode = statusCode;
         this.body = body;
         this.headers = headers;
+        this.statusMessage = options.statusMessage || '';
+        this.rawBody = options.rawBody || null;
+        this.request = options.request || null;
+        this.contentType = headers['content-type'] || headers['Content-Type'] || null;
+        this.parsed = options.parsed !== undefined ? options.parsed : true;
     }
     
     getStatusCode() {
@@ -27,6 +32,26 @@ class Response {
     getHeaders() {
         return this.headers;
     }
+
+    getStatusMessage() {
+        return this.statusMessage;
+    }
+
+    getRawBody() {
+        return this.rawBody;
+    }
+
+    getRequest() {
+        return this.request;
+    }
+
+    getContentType() {
+        return this.contentType;
+    }
+
+    isParsed() {
+        return this.parsed;
+    }
     
     isSuccess() {
         return this.statusCode >= 200 && this.statusCode < 300;
@@ -46,7 +71,8 @@ class Response {
     toArray() {
         return {
             status: this.statusCode,
-            body: this.body
+            body: this.body,
+            headers: this.headers
         };
     }
 }

package/lib/Route.js

@@ -0,0 +1,111 @@
+/**
+ * hlquery Node.js Client - Fluent Route API
+ *
+ * Copyright (C) 2021-2026, Carlos F. Ferry <carlos.ferry@gmail.com>
+ *
+ * This file is part of hlquery, released under the BSD License version 3.
+ */
+
+function requireNonEmptyString(value, label) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`${label} must be a non-empty string`);
+    }
+}
+
+function cleanRoute(route) {
+    if (route === null || route === undefined) {
+        return '';
+    }
+
+    if (Array.isArray(route)) {
+        return route
+            .map(segment => {
+                requireNonEmptyString(String(segment), 'Route segment');
+                return encodeURIComponent(String(segment).replace(/^\/+|\/+$/g, ''));
+            })
+            .filter(Boolean)
+            .join('/');
+    }
+
+    return String(route).replace(/^\/+|\/+$/g, '');
+}
+
+function joinPath(basePath, route) {
+    const base = String(basePath || '').replace(/\/+$/g, '');
+    const suffix = cleanRoute(route);
+
+    if (!suffix) {
+        return base || '/';
+    }
+
+    if (!base || base === '/') {
+        return `/${suffix}`;
+    }
+
+    return `${base}/${suffix}`;
+}
+
+/**
+ * Small Redis-style command builder for dynamic hlquery routes.
+ */
+class RouteCommand {
+    constructor(request, path) {
+        this.request = request;
+        this.path = path || '/';
+    }
+
+    route(route) {
+        return new RouteCommand(this.request, joinPath(this.path, route));
+    }
+
+    async call(method, body = null, queryParams = {}, options = {}) {
+        requireNonEmptyString(method, 'HTTP method');
+        return await this.request.execute(method.toUpperCase(), this.path, body, queryParams, options);
+    }
+
+    async get(queryParams = {}, options = {}) {
+        return await this.call('GET', null, queryParams, options);
+    }
+
+    async post(body = null, queryParams = {}, options = {}) {
+        return await this.call('POST', body, queryParams, options);
+    }
+
+    async put(body = null, queryParams = {}, options = {}) {
+        return await this.call('PUT', body, queryParams, options);
+    }
+
+    async patch(body = null, queryParams = {}, options = {}) {
+        return await this.call('PATCH', body, queryParams, options);
+    }
+
+    async delete(queryParams = {}, options = {}) {
+        return await this.call('DELETE', null, queryParams, options);
+    }
+
+    async del(queryParams = {}, options = {}) {
+        return await this.delete(queryParams, options);
+    }
+}
+
+/**
+ * Fluent command builder rooted at /modules/{name}.
+ */
+class ModuleRouteCommand extends RouteCommand {
+    constructor(request, name) {
+        requireNonEmptyString(name, 'Module name');
+        super(request, `/modules/${encodeURIComponent(name)}`);
+        this.name = name;
+    }
+
+    async syntax(queryParams = {}, options = {}) {
+        return await this.route('syntax').get(queryParams, options);
+    }
+}
+
+module.exports = {
+    RouteCommand,
+    ModuleRouteCommand,
+    cleanRoute,
+    joinPath
+};