agnostic-query

library1.10.5jsnpmunverified

agnostic-query v1.10.5 is a Type-safe fluent builder for portable query schemas. It provides a runtime-agnostic, database-agnostic query schema that can be serialized to JSON and transmitted over HTTP. The same schema drives Drizzle, Kysely, db0, or raw SQL, enabling query reuse across client and server. Key differentiators: zero runtime dependencies, tree-shakeable, supports complex logical nesting (and, or, not), tuple field paths for JSONB, and adapter-based architecture (Drizzle, Kysely, raw SQL). Active development with periodic releases on npm.

database

npm install agnostic-query

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AGNOSTIC-QUERY

agnostic-query

databasejavascriptv1.10.5

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.

✓ import { aq } from 'agnostic-query'

✗ import aq from 'agnostic-query'

aq is a named export, not default.

QuerySchema

✓ import { QuerySchema } from 'agnostic-query'

✗ import { QuerySchema } from 'agnostic-query'

Type import for TypeScript users. For runtime, use aq builder.

toDrizzle

✓ import { toDrizzle } from 'agnostic-query/adapters/drizzle'

✗ import { toDrizzle } from 'agnostic-query'

Adapter functions are exported from subpaths to enable tree-shaking. Importing from main entry may include unused adapters.

fromKysely

✓ import { fromKysely } from 'agnostic-query/adapters/kysely'

✗ import { fromKysely } from 'agnostic-query'

Same as toDrizzle, import from subpath.

Demonstrates fluent builder with type-safe methods to create a portable QuerySchema, then outputs JSON.

import { aq } from 'agnostic-query' interface User { name: string age: number status: string } const schema = aq<User>() .where('name', '=', 'Alice') .where('age', '>=', 18) .orderBy('name', 'asc') .limit(10) .offset(0) .toJSON() console.log(schema) // Output: // { // where: { // op: 'and', // conditions: [ // { field: ['name'], op: '=', value: 'Alice' }, // { field: ['age'], op: '>=', value: 18 } // ] // }, // orderBy: [{ field: ['name'], direction: 'asc' }], // limit: 10, // offset: 0 // }

Debug

Known issues

breakingAdapter imports must be from subpaths like 'agnostic-query/adapters/drizzle'. Direct import from 'agnostic-query' will not include adapter functions.

fix

Use import { toDrizzle } from 'agnostic-query/adapters/drizzle' instead of 'agnostic-query'.

affects: >=1.0.0

deprecatedThe operator is null currently requires two arguments. Future versions may change syntax.

fix

Use .where('field', 'is null') — no third argument.

affects: >=1.0.0

gotchaTuple field paths use array notation: .where(['address', 'city'], '=', 'Berlin') — not dot-separated strings.

fix

Always pass field paths as arrays of strings/numbers.

affects: >=1.0.0

gotchaPeer dependencies are large but optional. Installing all peers (Drizzle, Kysely, @tanstack/db) increases bundle size significantly if unused.

fix

Only install the peer deps you actually use. Tree-shaking removes unused adapter modules.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'agnostic-query/adapters/drizzle'

Adapter path typo or version incompatible with the installed package.

fix

Ensure package version >=1.0.0 and import from 'agnostic-query/adapters/drizzle'. If using monorepo, check package exports.

Type 'string' is not assignable to type 'FieldPath<User>'

Passing a dot-notated string instead of a tuple for nested fields.

fix

Use array path: ['address', 'city'] instead of 'address.city'.

Property 'toDrizzle' does not exist on type 'typeof import(...)'

Importing adapter from main entry instead of subpath.

fix

Import from 'agnostic-query/adapters/drizzle'.

Cannot use 'in' operator to search for 'where' in undefined

Calling .toJSON() on an empty builder without any conditions.

fix

Ensure at least one .where() or .orderBy() is called before .toJSON().

Upgrade

Version history

1.10.5latest on npm

Audit

Dependencies

zodoptionalPeer dependency for schema validation (^4.0.0). Required only if using Zod-based validation.

valibotoptionalPeer dependency for schema validation (^1.4.0). Required only if using Valibot-based validation.

drizzle-ormoptionalPeer dependency for Drizzle adapter (*). Required only when using toDrizzle().

@tanstack/dboptionalPeer dependency for TanStack DB adapter (*). Required only when using fromTanDb().

kyselyoptionalPeer dependency for Kysely adapter (*). Required only when using toKysely().

Agent activity

36 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Nahida-aa/agnostic-query ↗

packageagnostic-query ↗

homepagehttps://github.com/Nahida-aa/agnostic-query#readme ↗