The readme right now is kinda scary. There are a lot of complex code examples, and the glossary is gigantic. Instead, consider only showing the barebones installation instructions and description in the main readme, and moving the reference and full docs into a separate file or the repo wiki.

Example simple readme:

OBA API SDK

Small wrapper library that makes it easier to work with the OBA API.

Installation

npm install @maanlamp/oba-sdk

Usage

import SDK from "@maanlamp/oba-sdk";

const client = new sdk({
  key: "abcdef123456"
});

client.search("banaan")
  .then(console.log)
  .catch(console.error);

Full SDK Docs

Team

@maanlamp 🌜💡

License

MIT etc etc

I found a few things that prevent the /availability endpoint from working with the wrapper.

ID not working

An id for this endpoint would look like this |oba-catalogus|1201384, the problem however is that the | gets parsed to %7C which causes an error.

Unknown parameters

&pagesize=1&refine=false are given to any built url by default. But those parameters aren't known by the /availability endpoint, so it causes an error.

Sidenote: why are you setting refine=false on every normal /search? I thought refine=true returned extra info about the search results.

Supressed TypeError: Cannot read property '_text' of undefined

When I manually fixed (in a very dirty way, which breaks /search) the above issues I got a Supressed TypeError: Cannot read property '_text' of undefined

Hi there!

While I'm quite impressed by the technical prowess of this package, aren't some of the methods a bit over-engineered?

For example, the most basic usage of this package is (as per the readme)

(async () => {
  localStorage.clear();

  const api = new API({
      key: "ADD YOUR KEY HERE"
  });
  const stream = await api.createStream("search/banaan{5}");

  stream
    .pipe(stringify)
    .pipe(console.log)
    .catch(console.error);
})();

however, I feel like the (internal package) API could be way simpler by using a syntax like:

const api = new API({ key: "" });

api.search("banaan")
  .then(console.log)
  .catch(console.error);

you could then provide method shorthands for the available endpoints:

/search
/details
/refine
/schema
/index
/availability
/holdings
/resolver

Again, great job on all the fancy features! I'm a big fan of experimenting with these kind of things, and the minor is the perfect time to do it. I would be the last person to argue otherwise.

That being said, in a real-life use scenario, you don't need all the fancy options. I would even argue that it adds a whole lot of confusion for new users while it doesn't add much in terms of benefits.

https://github.com/maanlamp/OBA-wrapper/blob/master/js/index.js#L54

Could lead to weird and/or unsuspected errors.

has a public API that is usable by everyone to create very cool stuff;

The OBA API requires an authentication key that I can't seem to get in any way 👀

Now that I think about it, maybe you can add a note to the readme on how to retrieve an access key.

It would be incredibly useful to be able to play around with the demo test.html file without having to clone and install everything. You could keep a separate branch for this live demo or publish the whole master branch and add a link to the repo.

One of the reasons this package is browser only right now is the fact that it uses localStorage. Please consider making the storage engine configurable.

const api = new API({
  storage: window.localStorage
});

This allows the user to switch out localStorage for any storage engine or package that uses the same getItem and setItem syntax, like sessionStorage or even flavors of a memory or document store in Node!

https://github.com/maanlamp/OBA-wrapper#iteration-plan--planned-features

GH Projects is crazy useful for things like this. Also makes it easier for other people to visually parse 🙂