linkeddata / rdflib.js

Linked Data API for JavaScript
http://linkeddata.github.io/rdflib.js/doc/
Other
566 stars 146 forks source link

Typescript #373

Closed joepio closed 4 years ago

joepio commented 4 years ago

This PR converts most of RDFlib.js to Typescript (#355). It fixes various minor bugs and it adds a lot of documentation, using TypeDoc instead of JSDoc. Since it's such a big PR with most of the code changed, I've added a changelog with some of my thoughts. For the most important ones, I've already opened some issues, but for the less important ones I've just added some bullets below.

Changes included in PR #363 (already approved)

New changes

Compatibility with RDFJS taskforce and external datafactories

We've worked quite a bit on compliance with the TF (TaskForce) spec. The internal types (including the factory) extend Taskforce types, which live in a separate tf-types.ts file. This makes it easier to use RDFLib in combination with external, custom data factories.

Minor fixes

Possible bugs discovered, which are not fixed by this PR

Other things I noticed

Need review

Some thoughts on simplifying language

Getting started with Linked Data or RDF can be difficult, since it introduces quite a few new concepts. Since this library is powerful and generic, it might be one of the first and most important RDF tools that a developer will use. Therefore, we should try to use consistent langauge and keep synonyms to a minimum.

Notes for PR reviewer

joepio commented 4 years ago

I tried (see commit) replacing my TF types with those from @types/rdf-js, but it seems these are incompatible - both with RDFlib and with the original spec.

One of the most fundamental problems is that @types/rdf-js defines Term as a Union of its other Terms:

export type Term = NamedNode | BlankNode | Literal | Variable | DefaultGraph;

The RDF/JS spec defines Term as an abstract interface.

Since RDFlib uses custom terms (like Collection), it is compatible with the RDF/JS spec, and it works with my types, but it does not work with the types from @types/rdf-js. This problem with Term, unfortunately, trickles down quite a bit and makes it impossible to switch, at the moment.

There are a couple of things we can do here:

  1. Issue a PR for DefinitelyTyped/rdf-js, change Term to fit the spec. This does require that these changes do not break anything in rdf-js.
  2. Add the types to the RDF/JS repo.
  3. Do not import the @types/rdf-js types, but use my previous implementation.

@RubenVerborgh What are your thoughts on this?

megoth commented 4 years ago

To me it sounds like we want to start a process to make sure that the interfaces expressed by RDFJS are compatible with the work in rdflib. That is a lengthier discussion though, so I would suggest removing those parts and keep this PR simple.

We could of course mitigate that for now by having src/tf-types, but I think removing them altogether is better as a first step?

joepio commented 4 years ago

To me it sounds like we want to start a process to make sure that the interfaces expressed by RDFJS are compatible with the work in rdflib. That is a lengthier discussion though, so I would suggest removing those parts and keep this PR simple.

I'll make a separate issue for migrating to external types. (Edit: #374)

We could of course mitigate that for now by having src/tf-types, but I think removing them altogether is better as a first step?

Removing them has quite a big impact, I'd suggest we use the tf-types for now and do the migration to an external type definition later. As for now, the types in this PR seem to resemble the spec more closely.

joepio commented 4 years ago

@megoth

I believe testing in other applications (e.g. in mashlib, some node env) is smart before doing a definitive release and bumping the version. U agree that a pre-release is the way to go!

RubenVerborgh commented 4 years ago

About src/tf-types.ts, why do we copy instead of use? I only see disadvantages. There are more stakeholders to the RDF/JS domain than the maintainer of that one package. If there are incompatibilities, the package should be adjusted.

RubenVerborgh commented 4 years ago

Also, we should use proper naming. The word "taskforce" shouldn't occur in code, comments, or anywhere else. The proper terminology is the RDF/JS Data Model specification: https://rdf.js.org/data-model-spec/

joepio commented 4 years ago

@RubenVerborgh We copied from the @types/rdflib since these were the types specific to this repo. Since the repo is migrated to typescript in this PR, the @types/rdflib types are no longer useful - the ones in this PR are more accurate anyway, since they have to be fully internally consistent to even compile. For why I'm not using @types/rdfjs, see #374 (in short: I'm working on a PR to change Term, hopefully we can use these types after that is merged).

I've removed the 'taskforce' mentions.

RubenVerborgh commented 4 years ago

@joepio Thanks, lost track of all the issues. Only remnants now are TF prefixes as in TFDataFactory, which should also be replaced. Perhaps RdfJsDataFactory or RSDataFactory.

Happy to withdraw my objections after the last commits, and if we are using #374 to ensure that the interfaces are in fact copies and thus straight imports. If we can't something is wrong on either our side or their side.