README

OgerQuery

Ultra-fast lazy query engine for JavaScript & TypeScript — from Ogulcan Studio.

Fluent PascalCase chaining over any Iterable or AsyncIterable. Pipeline fusion. O(N) hash joins. Zero runtime dependencies.

import { Q } from 'ogerquery';

// Same logic as filter().map().slice().reduce() — but 73× faster on 1M rows
const total = Q(millionRows)
  .Where((r) => r.active)
  .Select((r) => r.amount * 2)
  .Take(10_000)
  .Sum();

The Speed Story

OgerQuery is built around what backend and data teams feel first: how fast chained filter / map / slice pipelines run on real datasets.

We benchmark head-to-head against native JavaScript Array methods — same logic, same output, no cherry-picking. Run it yourself:

npm run benchmark

Verified results — Bun 1.x, 1,000,000 rows, 5-run average

Headline benchmark — the one that makes people stop scrolling

Scenario: filter active rows → map amounts → take first 10k → sum

Native JS   ████████████████████  10.64 ms
OgerQuery   ▏                      0.15 ms   ← 73× faster

Full benchmark matrix

Numbers vary by CPU/OS — reproduce locally with npm run benchmark. Full methodology: docs/BENCHMARKS.md.

Why OgerQuery destroys native chains here

Native filter().map().slice() allocates two full intermediate arrays on 1M rows before you ever slice. OgerQuery fuses adjacent Where + Select + Take into one index loop and stops early — no wasted work, no GC pressure.

// Native — 10.64 ms on 1M rows (creates 2 intermediate arrays)
data
  .filter((r) => r.active)
  .map((r) => r.amount * 2)
  .slice(0, 10_000)
  .reduce((a, b) => a + b, 0);

// OgerQuery — 0.15 ms (single fused pass, early stop)
Q(data)
  .Where((r) => r.active)
  .Select((r) => r.amount * 2)
  .Take(10_000)
  .Sum();

Install

npm (recommended)

npm install ogerquery
# bun add ogerquery
# pnpm add ogerquery

Published by Ogulcan Studio — same team behind ogulcan-ui.

CDN (browser, zero build step)

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/OgerQuery.min.js"></script>
<script>
  const result = OgerQuery.Q([1, 2, 3, 4, 5])
    .Where((n) => n > 2)
    .Select((n) => n * 10)
    .ToArray();
  // [30, 40, 50]
</script>

TypeScript / Node

import { Q, QAsync } from 'ogerquery';

const topEmails = Q(users)
  .Where((u) => u.active)
  .OrderBy((u) => u.createdAt)
  .Select((u) => u.email)
  .Take(10)
  .ToArray();

const errors = await QAsync(logStream)
  .Where((e) => e.level === 'error')
  .Take(100)
  .ToArrayAsync();

Requirements: Node.js ≥ 18, Bun, Deno, or any ES2015+ browser.

Table of Contents

• Why Teams Choose OgerQuery
• Quick Start
• Documentation
• Operator Overview
• Enterprise Features
• Development
• Publish to npm
• License

Why Teams Choose OgerQuery

Works on arrays, generators, Sets, Maps, DOM NodeList, database cursors, ReadableStream, and any custom iterable.

Quick Start

Sync pipeline

import { Q } from 'ogerquery';

const result = Q([5, 3, 1, 4, 2])
  .Where((n) => n > 2)
  .OrderBy((n) => n)
  .Select((n) => n * 10)
  .ToArray();
// [30, 40, 50]

Predicate DSL

Q(users)
  .WhereEq('role', 'admin')
  .WhereGt('age', 18)
  .WhereIn('status', ['active', 'pending'])
  .ToArray();

Hash join

const details = Q(orders)
  .Join(
    customers,
    (o) => o.customerId,
    (c) => c.id,
    (o, c) => ({ orderId: o.id, customerName: c.name, total: o.amount }),
  )
  .ToArray();

Async streaming

import { QAsync } from 'ogerquery';

const rows = await QAsync(db.cursor('SELECT * FROM events'))
  .Where((e) => e.severity >= 3)
  .Select((e) => ({ id: e.id, msg: e.message }))
  .Take(500)
  .ToArrayAsync();

HTTP API integration

import { Q, parseQueryString, predicateFromParsedQuery } from 'ogerquery';

const { filter, page, pageSize } = parseQueryString(request.url);
const predicate = predicateFromParsedQuery(filter);

const pageResult = Q(db.getProducts())
  .Where(predicate)
  .Paginate(page ?? 1, pageSize ?? 20);

Documentation

Full docs in docs/ — shipped with the npm package.

Operator Overview

All sync operators have *Async terminal variants.

Enterprise Features

• Secure query parsing — depth limits, field allowlists, limit clamping
• Schema validation — validateFilterWithSchema for typed API filters
• Cursor pagination — stable large-dataset paging
• Cancellation — AbortSignal on async pipelines
• Web Streams — fromReadableStream / toReadableStream
• Property-tested — functor/filter laws via fast-check
• CI quality gates — typecheck, coverage, build on every push

Development

git clone https://github.com/OgulcanStudio/OgerQuery.git
cd OgerQuery
npm install
npm test              # unit + property tests
npm run typecheck     # strict TypeScript
npm run build         # ESM, CJS, IIFE → dist/
npm run benchmark     # prove the speed claims yourself

Publish to npm

Package is configured for the ogulcanstudio npm account (same as ogulcan-ui).

npm login                    # log in as ogulcanstudio
npm run build
npm publish --access public  # prepack runs build automatically

package.json includes author, repository, homepage, bugs, and publishConfig matching Ogulcan Studio standards.

License

MIT © Ogulcan Studio