Fluent query builder for filtering, transforming, and aggregating arrays of objects. Zero dependencies.

Installation

npm install @prsm/from

Usage

import { from, lt, eq, oneOf } from "@prsm/from"

const result = from(users)
  .where("age", lt(30))
  .where("role", eq("admin"))
  .sortBy("name", "asc")
  .skip(10)
  .take(5)
  .select(["name", "email"])
  .value()

Operators

// comparison
from(items).where("score", gt(90))
from(items).where("score", between(80, 100))

// strings and arrays
from(items).where("name", includes("test"))
from(items).where("name", startsWith("A"))
from(items).where("tags", lengthGt(2))
from(items).where("tags", empty())

// existence
from(items).where("deletedAt", missing())
from(items).where("email", exists())

// collection
from(items).where("status", oneOf(["active", "pending"]))

// custom predicate
from(items).where((item) => item.score > item.threshold)

Projection

from(items).select(["name", "email"])           // keep only these fields
from(items).omit(["password", "internal"])       // exclude these fields
from(items).map((item) => ({ label: item.name })) // transform

Aggregation

Computed fields are added in order and can reference each other:

from(students)
  .aggregate({
    total: add("math", "english", "science"),
    average: div("total", 3),
  })
  .omit(["total"])
  .value()

Operators: add, sub, mul, div. Accept field paths, literal numbers, or other aggregate operators.

Updates

Immutable by default:

// returns cloned array, original untouched
from(items).where("id", eq(1)).update("score", 100).value()

// wildcard maps array elements
from(items).update("tags.*", (t) => t.toUpperCase()).value()

Opt in to mutation:

from(items).where("id", eq(1)).updateMut("score", 100).value()

Sorting and Pagination

from(items).sortBy("score", "desc").skip(10).take(5).value()

Other

from(items).first()              // first match or undefined
from(items).count()              // number of results
from(items).groupBy("category")  // Record<string, T[]>
from(items).where(...).remove()  // returns matched items
from(items).where(...).removeMut().value()  // mutates in place

License

Apache-2.0