better type information (typescript)

[maku]

Although arangojs is written in typescript the type information is not really super strong.

e.g. when working with collections (super class BaseCollection) there are several methods which return type "Promise<any>". (and so on...)

Also, not all types are accessible via importing from 'arangojs'
e.g. when I want to use the type 'ArrayCursor' I have to:

import { ArrayCursor } from 'arangojs/lib/async/cursor'; or
import { ArrayCursor } from 'arangojs/lib/cjs/cursor';

Would it be possible to provide better type information?

[pluma]

One of the primary goal for the next major release (7.0) will be improved typings.

Sadly this is fairly tedious and requires a lot of manual verification because the HTTP API docs are sometimes a bit ambiguous.

[maku]

@pluma glad to here that. Is there something like a roadmap for arangojs?

[pluma]

No but if it's any consolation arangojs 7 is exactly what I'm currently working on.

[maku]

Great, thank you

[maku]

@pluma Is there any repository (branch or something) which can already be used? Because of the typing stuff is really a pain...

[pluma]

You can check out and build the feature/next-major branch on this repo if you want. I'm hoping to get the release out the door by the end of the month.

[maku]

@pluma Any timeframe when this (v7) will be released?

[NicolasDuran]

@pluma Thank you for the great work !
Do you have any idea when v7 will be released ?

Thank you again !

[maku]

@pluma Can you please give us an update about the typescript support? Current situation is far away from good. (BTW, is this an "official" ArangoDb project?)

[dsonet]

@pluma I suggest that you release alpha or beta versions so we can try it out easier and could help to polish it better sooner.
Thank you.

[spatialvlad]

Hello, thanks for working on improving TS experience for working with arangojs. Is there any time-frame or at least rough estimate when to expect 7.0?

[pluma]

My current plan is to release a preview version at some point in May. The CHANGELOG seems to be fairly complete and what's mostly missing right now is inlining the documentation (which also means properly documenting all the types and attributes in cases where the previous written documentation has gone out of sync with the actual code).

Before releasing a preview version, I would like to merge the PR. For this to happen I wanted to be certain what the breaking changes will be so I can release a minor version that will try to narrow the gap by adding new methods and tagging methods that will be removed as deprecated where possible.

As this entire ordeal takes a lot more effort than I originally anticipated, I will probably release the preview version from within the WIP branch instead, even if this messes up the GitHub tags later.

[pluma]

Good news everyone, I've released the current state of the v7 branch as a preview release:

https://github.com/arangodb/arangojs/releases/tag/v7.0.0-preview.0

You can install this version using the next tag by running npm install arangojs@next or yarn add arangojs@next.

Please be aware that this release includes a large number of breaking changes. The preview release also still lacks a lot of the inline documentation that has not yet been finalized.

As this is a preview release there is also no guarantee of no further breaking changes before the final 7.0.0 release.

[pluma]

I suggest subscribing to #660 if you want to track the release of v7 more closely.

v7.0.0-preview.1 has been released today. There likely won't be any significant API changes outside the methods for which documentation has not yet been inlined: https://github.com/arangodb/arangojs/tree/v7/docs/Drivers/JS/Reference

[Sharakai]

I'm currently looking at how we can make the TypeScript bindings "nicer" (subjectively), and wondering what minimum version of TypeScript the arangojs typings are aiming to support?

If you allow the minimum to be 2.8+, then conditional typings might allow for a cleaner TypeScript-friendly query API using generics on the aql helper method. For example:

// aql.ts
export interface AqlQuery<T = any> { ... }
export interface GeneratedAqlQuery<T = any> { ... }
export declare function aql<T = any>(templateStrings: TemplateStringsArray, ...args: AqlValue[]): GeneratedAqlQuery<T>;

export type QueryType<Q> = Q extends GeneratedAqlQuery<infer T> | AqlQuery<infer T> ? T : never;

And when running queries:

// database.ts
query<Q extends AqlQuery>(query: Q, options?: QueryOptions): Promise<ArrayCursor<QueryType<Q>>>;

This will then allow us to extract the query result type from the aql query for use when using database.query(AQL_QUERY).then(cursor => ..., e.g:

Happy to raise a PR if this is even vaguely correct thinking. 🙂

[pluma]

@Sharakai So if I understand you correctly, you suggest having the return type tied to the aql query object rather than having to define it at the callsite? That makes sense to me. I'll look into it.