npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@odata2ts/odata-query-builder

v0.18.1

Published

Allows for building type-safe OData queries with a fluent API

Downloads

19,319

Readme

npm (scoped)

OData Query Builder

The OData Query Builder allows for building type-safe OData queries for V2 and V4 services.

The query builder depends on generated models and q-objects to offer a powerful and easy-to-use API. These models and q-objects are generated via odata2ts out of an existing OData service.

The query builder offers operations which you probably know from SQL: select, filter, count, skip, top. You also get the ability to expand related entities which in turn can be filtered, selected or further expanded.

Selecting and expanding really means that the client has the power to shape the response structure. GraphQL should come to mind...

Additionally, OData V4 specifies even more functionalities like searching or aggregation.

What Does it Look Like?

A complex query could look like this:

import { createUriBuilderV4 } from "@odata2ts/odata-uri-builder";
import { qPerson } from "../generated-src/QTrippin.ts"

// In this minimal example the path ("People") as well as the q-object (qPerson) are provided manually.
// When using the generated service you will be provided with the builder and the proper q-object
createQueryBuilderV4("People", qPerson)
  .select("lastName", "age")                            // typesafe: only model attributes are allowed
  .filter(qPerson.userName.equals("russellwhyte"))      // typesafe: only string values are allowed for comparison with string props
  .expand("homeAddress")                                // typesafe: only expandable properties are allowed
  .expanding("trips", (builder, qTrip) => {             // typesafe: only expandable properties are allowed
    builder
      .select("tripId", "budget", "description")
      .top(1)
      .filter(qTrip.budget.gt(1000));
  })
  .build();

Result without encoding: /People?$select=LastName,Age &$filter=UserName eq 'russellwhyte' &$expand=HomeAddress,Trips($select=TripId,Budget,Description;top=5;$filter=Budget gt 1000)

Server Capabilities

Be aware that the OData service you use does not have to implement all querying capabilities.

When using an unsupported operation, then the server should respond with 501: Not Implemented (since the world's not perfect, you might face 500: Server Error instead).

Some OData services advertise their capabilities via annotations, but this is not covered by the OData spec. In any case odata2ts doesn't support annotations currently.

Inspiration

The approach of generating certain objects to provide type-specific and type-safe query capabilities is by no means an invention of odata2ts. On the contrary, odata2ts has been built in order to realize this approach for the domain of OData queries.

For us, this concept originates in two outstanding Java libraries which are designed for the domain of database queries: QueryDsl and jOOQ.

odata2ts diverges in some aspects from those libraries, but the similarities should be quite obvious, especially when it comes to filtering.

Documentation

Query Builder Documentation

Main documentation for the odata2ts eco system: https://odata2ts.github.io

Tests

See folder test for unit tests.

The example packages also contain some integration tests for querying.

Support, Feedback, Contributing

This project is open to feature requests, suggestions, bug reports, usage questions etc. via GitHub issues.

Contributions and feedback are encouraged and always welcome.

See the contribution guidelines for further information.

Spirit

This project and this module have been created and are maintained in the following spirit:

  • adhere to the OData specification as much as possible
    • support any OData service implementation which conforms to the spec
    • allow to work around faulty implementations if possible
  • stability matters
    • exercise Test Driven Development
    • bomb the place with unit tests (code coverage > 95%)
    • ensure that assumptions & understanding are correct by creating integration tests

License

MIT - see License.