hlquery-node-client 1.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: Node API CI
+
+on:
+  push:
+    branches: [ main, master, unstable ]
+  pull_request:
+    branches: [ main, master, unstable ]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+          cache-dependency-path: ./package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run offline smoke tests
+        run: npm run test:offline
+
+      - name: Validate package entry point
+        run: node -e "const sdk=require('./'); if (typeof sdk !== 'function') process.exit(1); console.log('entry point OK')"

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2021-2026, Carlos F. Ferry <carlos.ferry@gmail.com>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,316 @@
+<div align="center">
+  <img src="https://docs.hlquery.com/img/hlquery/2.png" alt="hlquery logo" width="200">
+</div>
+
+<div align="center">
+
+**A modular Node.js client library for hlquery.**
+
+[![Follow hlquery](https://img.shields.io/badge/Follow-%40hlquery-blue?logo=x&logoColor=white)](https://x.com/hlquery)
+[![Commit Activity](https://img.shields.io/github/commit-activity/m/hlquery/node-api)](https://github.com/hlquery/node-api/pulse)
+[![node-api](https://img.shields.io/badge/GitHub-node--api-181717?logo=github&logoColor=white)](https://github.com/hlquery/node-api/stargazers)
+[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+
+</div>
+
+# hlquery Node.js API Client
+
+### Installation
+
+Core client usage has no external dependencies. CSV support is built in.
+
+```bash
+npm install hlquery-node-client
+```
+
+```javascript
+const Client = require('hlquery-node-client');
+```
+
+For local development in this repository:
+
+```javascript
+const Client = require('./lib/Client');
+```
+
+### Quick Start
+
+```javascript
+const Client = require('hlquery-node-client');
+
+const client = new Client(process.env.HLQ_BASE_URL || 'http://localhost:9200', {
+  token: process.env.HLQ_TOKEN,
+  auth_method: 'bearer' // or 'api-key'
+});
+
+const health = await client.system().health();
+console.log('status:', health.getStatusCode());
+
+const collections = await client.collections().list(0, 10);
+console.log(collections.getBody());
+
+await client.collections().create('books', {
+  fields: [
+    { name: 'title', type: 'string' },
+    { name: 'content', type: 'string' }
+  ]
+});
+
+await client.documents().add('books', {
+  id: 'book-1',
+  title: 'Designing Data-Intensive Applications',
+  content: 'Distributed systems, data models, replication, and indexing.'
+});
+
+const results = await client.searchApi().search('books', {
+  q: 'distributed systems',
+  query_by: 'title,content',
+  limit: 10
+});
+console.log(results.getBody());
+```
+
+You can also set authentication later:
+
+```javascript
+client.setAuthToken('your_token_here', 'bearer');
+client.setAuthToken('your_api_key_here', 'api-key');
+```
+
+### API Surface
+
+Use nested API objects: `client -> resource -> action`, for example `client.collections().create(...)`.
+
+```javascript
+client.system().health();
+client.system().stats();
+client.system().info();
+client.system().status();
+client.system().metrics();
+client.system().connections();
+client.system().rocksdb();
+
+client.collections().list(offset, limit);
+client.collections().get(name);
+client.collections().create(name, schema);
+client.collections().update(name, schema);
+client.collections().delete(name);
+client.collections().getFields(name);
+
+client.documents().list(collection, params);
+client.documents().get(collection, id);
+client.documents().add(collection, document);
+client.documents().update(collection, id, document);
+client.documents().delete(collection, id);
+client.documents().import(collection, documents);
+client.documents().export(collection, params);
+client.documents().facetCounts(collection, params);
+client.documents().addCSV(collection, filePath, options);
+
+client.searchApi().search(collection, params);
+client.searchApi().vectorSearch(collection, params);
+client.searchApi().multiSearch(searches);
+client.searchApi().globalSearch(params);
+client.searchApi().sql(collection, sql);
+
+client.aliases().create(name, params);
+client.aliases().update(name, params);
+client.aliases().delete(name);
+client.synonyms().create(collection, id, synonym);
+client.stopwords().create(collection, params);
+client.overrides().create(collection, id, override);
+client.keys().create(params);
+client.executeRequest(method, path, body, query);
+```
+
+### Collections
+
+```javascript
+const collections = client.collections();
+
+await collections.create('books', {
+  fields: [
+    { name: 'title', type: 'string' },
+    { name: 'content', type: 'string' },
+    { name: 'category', type: 'string', facet: true }
+  ]
+});
+
+await collections.get('books');
+await collections.getFields('books');
+await collections.update('books', schema);
+await collections.delete('books');
+```
+
+### Documents
+
+```javascript
+const documents = client.documents();
+
+await documents.add('books', {
+  id: 'book-1',
+  title: 'Designing Data-Intensive Applications',
+  content: 'Distributed systems, data models, replication, and indexing.'
+});
+
+await documents.update('books', 'book-1', { title: 'DDIA' });
+await documents.delete('books', 'book-1');
+
+await documents.import('books', [
+  { id: 'book-2', title: 'Database Internals', content: 'Storage engines and indexes.' }
+]);
+
+await documents.addCSV('reports', './files/metrics.csv', {
+  id: 'metrics_q1',
+  document: { source_type: 'csv' }
+});
+```
+
+`addCSV()` parses a local CSV file, flattens rows into text, and indexes the generated document. It does not require extra packages.
+
+### Search
+
+```javascript
+const search = client.searchApi();
+
+await search.search('books', {
+  q: 'title:database OR content:index*',
+  query_by: 'title,content',
+  filter_by: 'category:technical',
+  sort_by: '_text_match:desc',
+  facet_by: 'category',
+  limit: 10,
+  offset: 0
+});
+
+await search.multiSearch([
+  { collection: 'books', q: 'database', query_by: 'title,content' },
+  { collection: 'articles', q: 'database', query_by: 'title,body' }
+]);
+
+await search.vectorSearch('books', {
+  vector_query: [0.12, 0.34, 0.56],
+  vector_by: 'embedding',
+  limit: 10
+});
+```
+
+Common search parameters:
+
+- `q`: query string, including field clauses, phrases, boolean operators, and wildcards.
+- `query_by`: searchable fields as a string or array.
+- `filter_by`: filter expression.
+- `sort_by`: sort expression.
+- `facet_by`: facet fields.
+- `limit` / `offset`: pagination.
+- `page` / `per_page`: alternate pagination.
+
+### SQL
+
+SQL queries are supported through the search API and through the interactive talk shell.
+
+```javascript
+const response = await client.searchApi().sql(
+  'products',
+  'SELECT id, title, price FROM products ORDER BY price DESC LIMIT 5;'
+);
+
+const rows = response.getBody().rows || [];
+
+await client.sql('SHOW COLLECTIONS;');
+await client.execSql("INSERT INTO products (id, title) VALUES ('sku-9', 'Camp Stove');");
+```
+
+Talk shell example:
+
+```text
+localhost:9200> sql: select title,id from music LIMIT 2;
+
+SQL rows for `select title,id from music LIMIT 2;`:
++--------------------------------+------------------------------------------+
+| id                             | title                                    |
++--------------------------------+------------------------------------------+
+| music_artist-profile-beyonce   | Artist Profile: Beyonce                  |
+| music_artist-profile-kendrick- | Artist Profile: Kendrick Lamar           |
+| lamar                          |                                          |
++--------------------------------+------------------------------------------+
+2 results shown.
+Search completed in 19 ms.
+```
+
+### Search Management
+
+```javascript
+const aliases = client.aliases();
+const synonyms = client.synonyms();
+const stopwords = client.stopwords();
+const overrides = client.overrides();
+
+await aliases.create('books_current', { collection_name: 'books_v2' });
+
+await synonyms.create('books', 'cars', {
+  root: 'car',
+  synonyms: ['auto', 'automobile']
+});
+
+await stopwords.create('books', { word: 'the' });
+
+await overrides.create('books', 'boost_featured', {
+  rule: { query: 'featured', match: 'exact' },
+  includes: [{ id: 'doc-1', position: 1 }],
+  excludes: []
+});
+```
+
+### Responses
+
+All API methods return a `Response` object.
+
+```javascript
+const response = await client.system().health();
+
+response.getStatusCode();
+response.getBody();
+response.isSuccess();
+response.isError();
+response.getError();
+response.toArray();
+```
+
+### Errors
+
+```javascript
+const { RequestException, AuthenticationException, ValidationException } = require('./lib/Exceptions');
+
+try {
+  const result = await client.searchApi().search('books', { q: 'test' });
+  if (result.isError()) {
+    console.log(result.getError());
+  }
+} catch (error) {
+  if (error instanceof RequestException) {
+    console.log('request failed:', error.message, error.statusCode);
+  } else if (error instanceof AuthenticationException) {
+    console.log('auth failed:', error.message);
+  } else if (error instanceof ValidationException) {
+    console.log('validation failed:', error.message);
+  } else {
+    throw error;
+  }
+}
+```
+
+### Requirements
+
+- Node.js >= 12.0.0
+- No external dependencies required for core client usage
+
+### Features
+
+- Modular classes for collections, documents, search, aliases, overrides, synonyms, stopwords, and system APIs.
+- Bearer token and X-API-Key authentication.
+- Flexible parameter formats.
+- Automatic searchable-field detection when fields are not specified.
+- SQL helpers for collection-bound and top-level SQL execution.
+- Response wrapper with status, body, and error helpers.
+- Built-in validation and async/await support.