@prsm/from

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

Installation

npm install @prsm/from

Usage

import{from,lt,eq,oneOf}from"@prsm/from"constresult=from(users).where("age",lt(30)).where("role",eq("admin")).sortBy("name","asc").skip(10).take(5).select(["name","email"]).value()

Operators

// comparisonfrom(items).where("score",gt(90))from(items).where("score",between(80,100))// strings and arraysfrom(items).where("name",includes("test"))from(items).where("name",startsWith("A"))from(items).where("tags",lengthGt(2))from(items).where("tags",empty())// existencefrom(items).where("deletedAt",missing())from(items).where("email",exists())// collectionfrom(items).where("status",oneOf(["active","pending"]))// custom predicatefrom(items).where((item)=>item.score>item.threshold)// wildcard paths - match if any element satisfies the operatorfrom(items).where("tags.*",eq("featured"))from(items).where("departments.*.members.*.skill",eq("rust"))

Projection

from(items).select(["name","email"])// keep only these fieldsfrom(items).omit(["password","internal"])// exclude these fieldsfrom(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 untouchedfrom(items).where("id",eq(1)).update("score",100).value()// wildcard maps array elementsfrom(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 undefinedfrom(items).count()// number of resultsfrom(items).groupBy("category")// Record<string, T[]>from(items).where(...).remove()// returns matched itemsfrom(items).where(...).removeMut().value()// mutates in place

License

Apache-2.0