madapes
Repositories
7
 Projects Packages

@madapes/query-engine (0.1.6)

Published 2026-02-15 13:57:53 +00:00 by vlad

Installation

@madapes:registry=
npm install @madapes/query-engine@0.1.6
"@madapes/query-engine": "0.1.6"

About this package

@madapes/query-engine

High-performance query engine with UQF (Unified Query Format) support for Node.js.

Installation

npm install @madapes/query-engine

Prerequisites

This package uses native FFI bindings to the Rust query engine. You need:

  1. The compiled native library (libquery_engine.dylib on macOS, libquery_engine.so on Linux, query_engine.dll on Windows)
  2. Node.js >= 18.0.0

To build the native library:

cd /path/to/query-engine
cargo build --release

Then copy the library to bindings/nodejs/native/.

Usage

Basic Example

import { Engine, Documents, F, query } from '@madapes/query-engine';

// Create an engine and documents collection
const engine = new Engine();
const docs = new Documents();

// Add documents
docs.addMany([
  { id: 1, name: 'Alice', age: 30 },
  { id: 2, name: 'Bob', age: 25 },
  { id: 3, name: 'Charlie', age: 35 },
]);

// Build and execute a query
const result = engine.find(
  query()
    .filter(F.gte('age', 30))
    .sort('age', 'asc')
    .limit(10)
    .build(),
  docs
);

console.log(result.hits); // [{ id: 1, ... }, { id: 3, ... }]

// Clean up
docs.dispose();
engine.dispose();

Query Builder

The query builder provides a fluent API for constructing queries:

import { F, query } from '@madapes/query-engine';

// Complex filter
const q = query()
  .filter(
    F.and(
      F.eq('status', 'active'),
      F.or(
        F.gt('age', 21),
        F.eq('vip', true)
      )
    )
  )
  .sort('created_at', 'desc')
  .limit(20)
  .offset(0)
  .fields('id', 'name', 'email')
  .timeout(5000)
  .build();

Available Filter Operators

Comparison

  • F.eq(field, value) - Equal
  • F.ne(field, value) - Not equal
  • F.gt(field, value) - Greater than
  • F.gte(field, value) - Greater than or equal
  • F.lt(field, value) - Less than
  • F.lte(field, value) - Less than or equal
  • F.between(field, low, high) - Between range

Set

  • F.in(field, values) - In array
  • F.nin(field, values) - Not in array

String

  • F.prefix(field, prefix) - Starts with
  • F.contains(field, substring) - Contains
  • F.regex(field, pattern) - Matches regex

Array

  • F.all(field, values) - Array contains all
  • F.size(field, size) - Array size equals
  • F.elemMatch(field, filter) - Element matches filter

Logical

  • F.and(...filters) - All filters match
  • F.or(...filters) - Any filter matches
  • F.not(filter) - Filter does not match

Existence/Type

  • F.exists(field, exists?) - Field exists
  • F.type(field, type) - Field is of type
  • F.true() - Always matches
  • F.false() - Never matches

Numeric

  • F.mod(field, divisor, remainder) - Modulo equals

Cancellation

import { Engine, Documents, CancelToken, F, query } from '@madapes/query-engine';

const engine = new Engine();
const docs = new Documents();
const token = new CancelToken();

// Start cancellation after 100ms
setTimeout(() => token.cancel(), 100);

try {
  const result = engine.findCancellable(
    query().filter(F.true()).build(),
    docs,
    token
  );
} catch (err) {
  if (err.code === QeErrorCode.Cancelled) {
    console.log('Query was cancelled');
  }
}

token.dispose();
docs.dispose();
engine.dispose();

Convenience Functions

import { findInMemory, countInMemory, F, query } from '@madapes/query-engine';

const docs = [
  { id: 1, status: 'active' },
  { id: 2, status: 'inactive' },
];

// One-shot find
const result = findInMemory(
  query().filter(F.eq('status', 'active')).build(),
  docs
);

// One-shot count
const count = countInMemory(
  query().filter(F.true()).build(),
  docs
);

API Reference

Engine

  • new Engine(config?) - Create a new engine
  • Engine.version - Get library version
  • engine.validate(query) - Validate a query
  • engine.find(query, docs) - Execute a find query
  • engine.findCancellable(query, docs, token) - Execute with cancellation
  • engine.count(query, docs) - Execute a count query
  • engine.cacheStats - Get cache statistics
  • engine.clearCache() - Clear the plan cache
  • engine.dispose() - Release resources

Documents

  • new Documents() - Create a new collection
  • docs.add(doc) - Add a single document
  • docs.addMany(docs) - Add multiple documents
  • docs.count - Get document count
  • docs.dispose() - Release resources

CancelToken

  • new CancelToken() - Create a new token
  • token.cancel() - Signal cancellation
  • token.isCancelled - Check if cancelled
  • token.dispose() - Release resources

License

MIT

Dependencies

Development Dependencies

ID Version
@napi-rs/cli ^2.18.4
@types/node ^20.0.0
typescript ^5.0.0

Optional Dependencies

ID Version
@madapes/query-engine-darwin-arm64 0.1.6
@madapes/query-engine-darwin-x64 0.1.6
@madapes/query-engine-linux-arm64-gnu 0.1.6
@madapes/query-engine-linux-x64-gnu 0.1.6
@madapes/query-engine-win32-x64-msvc 0.1.6

Keywords

query json filter database uqf
Details
npm
2026-02-15 13:57:53 +00:00
8
Mad Apes
MIT
20 KiB
Assets (1)
query-engine-0.1.6.tgz 20 KiB
Versions (3) View all
0.1.7 2026-02-16
0.1.6 2026-02-15
0.1.5 2026-02-14