kuery

library2.0.0jsnpmunverified

Kuery is a zero-dependency, MongoDB-style in-memory query engine for JavaScript collections. Version 2.0.0 (stable, actively maintained) compiles queries to native closures for performance. Full TypeScript support with type-safe dot-path queries and dual ESM+CJS exports. Key differentiator: AST-based pipeline enabling pre-compilation, inspection, and custom operators — unlike simple filter utilities. Supports comparison, inclusion, logical, and element operators with methods like find, findOne, sort, skip, limit, and test.

database

npm install kuery

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · KUERY

kuery

databasejavascriptv2.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Kuery

✓ import Kuery from 'kuery'

✗ const Kuery = require('kuery')

ESM default import; CJS require also works via Kuery.default in v2 but direct require is backward-compatible

compileFilter

✓ import { compileFilter } from 'kuery'

✗ import compileFilter from 'kuery/compileFilter'

Remove incorrect subpath import; compileFilter is a named export from 'kuery'

KueryError

✓ import { KueryError } from 'kuery'

✗ const { KueryError } = require('kuery')

Named export, also works with destructured require in CJS

findOne (standalone)

✓ import { findOne } from 'kuery/collection'

✗ import { findOne } from 'kuery'

Standalone findOne is exported from 'kuery/collection' subpath; Kuery.findOne is a method, different behavior (asserts uniqueness)

Creates a Kuery instance with a MongoDB-style query filter, then uses .find(), .sort(), and dot-path queries on a sample collection.

import Kuery from 'kuery'; const users = [ { id: 1, name: 'Alice', age: 25, role: 'admin', address: { city: 'NYC' } }, { id: 2, name: 'Bob', age: 17, role: 'user', address: { city: 'LA' } }, { id: 3, name: 'Carol', age: 30, role: 'mod', address: { city: 'NYC' } }, ]; const admins = new Kuery({ role: 'admin' }).find(users); // [{ id: 1, name: 'Alice', ... }] const adultNYC = new Kuery({ age: { $gte: 18 }, 'address.city': 'NYC' }).find(users); // [{ id: 1, ... }, { id: 3, ... }] const sorted = new Kuery({}).sort({ name: -1 }).find(users); // [{ id: 2, name: 'Bob' }, { id: 3, name: 'Carol' }, { id: 1, name: 'Alice' }]

Debug

Known issues

breakingIn v2, standalone findOne from 'kuery/collection' returns first match or undefined, while Kuery.findOne() asserts exactly one result (throws if 0 or 2+). In v1, Kuery.findOne returned the first match without assertion.

fix

Use Kuery.findOne() for uniqueness assertion, or import standalone findOne from 'kuery/collection' for first-match behavior.

affects: >=2.0.0

gotchaImporting 'kuery/collection' subpaths may fail in bundlers that do not support package.json exports. Use full path 'kuery/collection' (no index).

fix

Ensure bundler supports subpath exports, or import from 'kuery' and use Kuery static methods.

affects: >=2.0.0

deprecatedIn v1, require('kuery') returned a constructor without default export. In v2, ESM default import is preferred but CJS require works via Kuery.default. Direct require is deprecated for ESM environments.

fix

Use ESM import or require('kuery').default in CJS.

affects: >=1.0.0 <2.0.0

gotchaKuery.findOne() does not guarantee unique ID; it only throws if 0 or multiple matches. For a unique lookup, ensure your query matches exactly one document.

fix

Design queries to be unique (e.g., on _id field) before calling findOne.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'kuery/collection'

Importing a subpath that is not exported in package.json or bundler not respecting exports.

fix

Update to bundler that supports subpath exports (Webpack 5+, Vite, etc.) or import from 'kuery' main.

'KueryError' is not exported from 'kuery'

Trying to import KueryError as a default export or from wrong path in v2.

fix

Use 'import { KueryError } from 'kuery'' (named import).

TypeError: Kuery is not a constructor

Using require('kuery') in ESM context where default export is not assigned to module.exports.

fix

Use ESM import or require('kuery').default.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/surikaterna/kuery ↗

packagekuery ↗

homepagehttps://github.com/surikaterna/kuery#readme ↗