Hacker News Reader

Comment by nox101 | Hacker News Reader

No, that's poor API. If it wants to generate HTML it should return it's root element.

Let's say I want to add a random face to every div with class "face". With this API have to generate ids. With an API that returns a root element it's trivial and it's not duplicating work (inserting elements into the DOM) that already exists.

Taking a selector would not be much better because it would again be duplicating work and make it harder to customize usage.

Taking a parent element for it to insert into would also be a poor API because it makes it harder to insert next to a sibling.

A good API would be one of

    const face = generate()
    someElem.appendChild(face);

    const face = generate()
    someElem.appendChild(face.domElement);

    const face = generate()
    someElem.appendChild(face.html());   // assumes it can render to something else too

View on HN

> Taking a parent element for it to insert into would also be a poor API because it makes it harder to insert next to a sibling.

To extend the documentation example, wouldn't you just have "my-div-id-sibling" already and call

    display("my-div-id", face);
    display('my-div-id-sibling", someOtherFace);

Like almost all discussions that use language like "good API" or "bad API" this seems to me entirely personal preference. Personally I find anything where I end up having to call appendChild() myself a bad API.

No, that would not be better. Consider

    document.querySelectorAll('classIWantFacesIn').forEach(elem => {
       const face = generate();
       elem.id = `face-${crypto.randomUUID()}`; // this line should not be needed
       display(elem.id, face);
    });

With the current API I'm required to make ids and make sure they don't collide with other elements. Vs

    document.querySelectorAll('classIWantFacesIn').forEach(elem => {
       const face = generate();
       elem.appendChild(face.domElement);
    });

Now, no id is needed. It's objectively a better API to not need the id.

(faces.js dev here)

A nice thing about the current API is the face objects can be trivially serialized to JSON, which I need do in the application I originally wrote the library for.

Also the `display` function works with a DOM element as the first argument too, in which case you don't need to make up an ID. That's how I use it.

That being said, the API might not be perfect, but you should at least appreciate that it's been stable since v1 in 2015!

See other response this thread why passing in a DOM element is also not a good API.

That said, I wouldn't have spoken up if someone hadn't claimed the API was good. Any one who makes a useful library that provides useful functionality people want is great!

> it's been stable since v1 in 2015!

That's awesome!

I agree the API could be better, but note that you don't have to use IDs - you can also pass the parent element to display directly: https://github.com/zengm-games/facesjs/blob/master/src/displ...

As mentioned, that's still a poorer API than just returning a root element.

Consider...

    // insert after every link
    document.querySelectorAll('a.funny').forEach(elem =>
      const face = generate();
      const parentForFace = document.createElement('span');
      elem.appendChild(parentForFace);
      display(parentForFace);
    });

    // insert after every link
    document.querySelectorAll('a.funny').forEach(elem =>
      const face = generate();
      elem.after(face.domElement);
    });

Taking a parent element is still a poor API

Reply on news.ycombinator.com