TypeScript type definitions

[laurentgoudet]

UPDATE: We are going to do this across the board. We will use this issue to track each repository.

• googleapis/google-api-nodejs-client
• googleapis/google-auth-library-nodejs
• googleapis/google-p12-pem
• googleapis/node-gtoken
• googleapis/cloud-trace-nodejs
• googleapis/cloud-debug-nodejs
• googleapis/cloud-profiler-nodejs
• googleapis/nodejs-promisify
• googleapis/nodejs-projectify
• googleapis/nodejs-paginator
• googleapis/gcs-resumable-upload
• googleapis/gcp-metadata
• googleapis/nodejs-bigquery
• googleapis/nodejs-proto-files
• googleapis/nodejs-storage
• googleapis/google-cloud-kvstore
• googleapis/gce-images
• googleapis/nodejs-firestore
• googleapis/nodejs-common-grpc
• googleapis/nodejs-common
• googleapis/nodejs-error-reporting
• googleapis/gax-nodejs
• googleapis/nodejs-translate
• googleapis/nodejs-dns
• googleapis/nodejs-logging-winston
• googleapis/nodejs-logging-bunyan
• googleapis/nodejs-resource
• googleapis/nodejs-rcloadenv
• googleapis/nodejs-datastore
• googleapis/nodejs-spanner
• googleapis/nodejs-pubsub
• googleapis/nodejs-precise-date
• googleapis/nodejs-compute
• googleapis/nodejs-bigtable
• googleapis/nodejs-redis
• googleapis/nodejs-vision
• googleapis/nodejs-text-to-speech
• googleapis/nodejs-os-login
• googleapis/nodejs-dataproc
• googleapis/nodejs-bigquery-data-transfer
• googleapis/nodejs-video-intelligence
• googleapis/nodejs-speech
• googleapis/nodejs-monitoring
• googleapis/nodejs-logging
• googleapis/nodejs-language
• googleapis/nodejs-cloud-container
• googleapis/nodejs-dlp
• googleapis/nodejs-tasks
• googleapis/nodejs-redis
• googleapis/nodejs-automl
• googleapis/nodejs-kms
• googleapis/nodejs-iot
• googleapis/nodejs-scheduler
• googleapis/nodejs-security-center
• googleapis/nodejs-asset
• googleapis/nodejs-talent
• googleapis/nodejs-irm

---

Now that TypeScript has a much better support for the npm ecosystem (https://github.com/Microsoft/TypeScript/wiki/Typings-for-npm-packages), it'll be great if you guys could ship type definitions alongside the package. Maybe there's way to do it during release from the dox JSON output files.

[stephenplusplus]

UPDATE: 5/9/18

We are moving some libraries to TypeScript. We're getting there, please subscribe to this issue for updates :)

---

Original post, 11/19/15

⚠️ I'm not very well versed in TypeScript and its conventions.

I think this would be a cool thing, but I'm not sure it's the right time, and possibly not the right place.

⌛ Time

We haven't stabilized to the point we're comfortable tagging 1.0. We're still making pretty sweeping changes, so adding the weight of maintaining the definition file could quickly lead to inconsistencies.

However, the suggestion of dox -> definition file makes a lot of sense... if there was such a transformer, we could easily integrate that at any time and not worry about inconsistencies.

🌎 Place

I came across this: https://github.com/DefinitelyTyped/DefinitelyTyped, which looks to be hosting definition files for popular libraries, where the definition files are contributed by the community and not the authors of the library. This separation would be nice, since choosing to support TypeScript and shipping our own definition files caters to only one of many possible use cases. Having a separate place and the help from the community would be really nice.

[laurentgoudet]

The issue with https://github.com/DefinitelyTyped/DefinitelyTyped is that these type definitions are not versionned with the underlying repos, which makes TypeScript useless if the thirdparty has an API change but the type definitions haven't been updated (i.e., the compiler won't fail). For that reason, as far as I'm aware, the TypeScript team is currently pushing for the type definitions to be hosted directly in the projects' repos and specified in the package.json.

Fair point on the 1.0 though. Unfortunately I'm not aware of any dox to .d.ts transformer :(. Code written in TypeScript gets its type definitions file generated by the compiler (and won't have redundant JSDoc type comments anyway).

[stephenplusplus]

Let's keep this open and see if we get more input. 1.0 is probably, almost definitely, not going to happen before February 2016, so we have a while to see what conventions might develop in the meantime. Until then, the DefinitelyTyped solution would be the best solution. If you (or anyone seeing this) decides to pop us in there, ping me anytime if there are any questions along the way that I can help with.

[jasonswearingen]

i wrote my own definitions _for datastore_, i am going to publish the definitions on definitelyTyped but haven't done so yet (haven't debugged/tested my app yet)

here's the definitions for you if you like
https://gist.github.com/jasonswearingen/b2619b1d7d4991452131

[jasonswearingen]

by the way, the datastore api does seem a bit immature (besides the obvious no Promises) so i'm not so sure writing typings is so important at this point. I write typings because it helps me learn a new api.

[stephenplusplus]

Thanks for sharing that!

the datastore api does seem a bit immature

Yeah, it will be shaken up pretty good by #897.

[JustinBeckwith]

This came up in the node.js blog post btw:
https://cloudplatform.googleblog.com/2016/03/Node.js-on-Google-App-Engine-goes-beta.html

Also highly sought after in the google api node.js client:
googleapis/google-api-nodejs-client#503

[danvk]

FYI, you can distribute an index.d.ts file with the node module and avoid DefinitelyTyped's versioning issues.

[Splaktar]

We're also using this library with TypeScript and could really use a type definition for it. As mentioned above, just including a simple index.d.ts in the root of the node module would help a lot and keep things simple until you are ready to publish something to @types/google-cloud-node.

[Splaktar]

We're using this atm, but it's just some patchwork to try and give us some basic typing in our code. But we keep hitting cases where we need to add more, which causes productivity slow downs.

declare module 'google-cloud' {
  import {Readable, Writable} from 'stream';
  class Storage {
    bucket (name: string): StorageBucket;
  }
  class StorageBucket {
    file (name: string): StorageFile;
    getFiles (options: Object, callback: Function): void;
  }
  class StorageFile {
    createReadStream (): Readable;
    createWriteStream (options: any): Writable;
    delete(callback: Function): void;
  }
  class PubSub {
    topic (name: string) : Topic;
    subscription (name: string): any;
    createTopic (name: string, callback: Function): void;
    getTopics (callback: Function): void;
  }
  class Topic {
    publish (message: Object, callback: Function): void;
    subscribe (subscriptionName: string, options: Object, callback: Function): void;
    delete (callback: Function): void;
  }
  class Subscription {
    pull (options: Object, callback: Function): void;
    on (listenerType: string, callback: Function): void;
    removeListener (listenerType: string, Function): void;
  }
  class BigQuery {
    createDataset(id: string, callback: Function): void;
    dataset(id: string): Dataset;
    getDatasets(query: Object, callback: Function): void;
  }
  class Dataset {
    table(id: string): Table;
    exists(callback: Function): void;
    create(callback: Function): void;
  }
  class Table {
    insert(rows: Object, options: Object, callback: Function): void;
  }
  class GCloud {
    storage (options: any): Storage;
  }
  function gcloud (options: any): GCloud;
  function bigquery (options?: any): BigQuery;
  function storage (options?: any): Storage;
  function pubsub (options?: any): PubSub;
}

[justinfagnani]

I think it would be better if the type declarations were maintained here, rather than in DefintielyTyped. They can be referenced from a typings property of package.json. Then users will always get the correct version of types for the version of the client library.

One thing that would help TypeScript declarations, and future ECMAScript module compatibility would be to not export functions as modules with code like module.exports = Datastore here which is not supported in ES6, but to export individual symbols, like module.exports.Datastore = Datastore. Then classes will be importable like so:

import {Datastore} from '@google-cloud/datastore';

[chadbr]

quick update - I spent a couple of days on this and really got nowhere.

From what I can tell by looking at a lot of the auto-gen'd libs, we should really be generating a set of .d.ts definitions from the .proto definitions for api/ver.

This is a little too much work for me at the moment.

As an aside -- I ran across this:

https://github.com/Microsoft/dts-gen

When I get some time in the next couple of weeks, I'll give it a go.

[jasonswearingen]

i mentioned this before, but I wrote (hand written) definitions for cloud datastore, anyone who wants feel free to use it: https://gist.github.com/jasonswearingen/b2619b1d7d4991452131

I was going to publish on DefinitelyTyped but never got around to it.

[osdiab]

I too would be interested in seeing this support come to existence, as AWS and Azure both have typings available—excited to see progress on this.

[tastywheattasteslikechicken]

I'm going to throw my voice in for this -- typescript is gaining in popularity (3x higher as a search term since when this issue was created) and it would be great to get official support.

[mmmeff]

Not to mention Google just accepted Typescript as an officially supported internal language. I've been waiting to see how the language is adopted for a few years now and I'm finally biting the bullet and kicking off a new project with it. One that uses google-cloud APIs.

Definitely throwing my 👍 on this

[lukesneeringer]

At this point, this is probably something we are going to do. However, I can not yet give any reliable promise on when / the timing.

[akomarovsky]

Adding my 👍 to add Typescript defintion

[afdalwahyu]

btw, now you can install via npm:

npm install --save-dev @types/google-cloud__storage

[beaulac]

Just submitted a PR.

Hopefully it's published soon 🤞

[julien-c]

@beaulac It's just for datastore though, no?

[beaulac]

@julien-c Yes, indeed. Sorry to get your hopes up 😓

Considering the large number of different packages (in varying alpha/beta/GA states), it might be more useful to track definition requests specifically per service.

[atrauzzi]

Maybe worth raising a concern internally over having this as a more formalized effort then?

[nbperry]

I would be more than willing to help with this effort. I have a little experience doing this from updating the definitions for google-cloud__storage in the past.

[MagsMagnoli]

@laurentgoudet please add dialogflow to this list!

[csidell-earny]

Hope bigtable is included soon

[IchordeDionysos]

Isn't there a way to compile GRPC Types to Typescript?
Seems like internally Google creates Protobuf types for every API for using it with GRPC and to generate documentation for the APIs.

So wouldn't a compiler to Typescript simplify, make things scalable and keep everything up-to-date?

[grant]

@JustinBeckwith Can you give an update on the state of this issue?

[bcoe]

@grant for our gRPC-based libraries, we're gradually moving towards TypeScript-based generators, rather than JavaScript; as we make this migration, these libraries (nodejs-vision, nodejs-speech, etc.,) will start to land types.

[garyo]

Any news on type decls for googleapis/nodejs-compute (aka @google-cloud/compute)?

[JustinBeckwith]

Greetings @garyo! That is the one module that likely won't be getting types 😬 I would highly recommend using https://github.com/googleapis/google-api-nodejs-client instead.

[garyo]

I see, thanks @JustinBeckwith . I'll check out this new module. If that old module is deprecated (?) then maybe something in the README would be useful. There's a lot of examples floating around out there using @google-cloud/compute.

Hmm, just looking at google-api-nodejs-client, there's no doc for compute at all... see https://googleapis.dev/nodejs/googleapis/latest -- should I file an issue there?

[JustinBeckwith]

Yeah, it's not deprecated as of now, but there's so much code it would take a very, very long time to support types. On the samples - great point! Before we even considered deprecating that module, we would need to have a plan in place.

[JustinBeckwith]

Folks - I think we're ready to call this one :) There may be one or two stragglers out there, but we should be able to follow up as needed with package specific bugs. Thanks for being patient here! And please do let us know if we missed anything.

[chadbr]

Great work @JustinBeckwith and team -- really appreciate it

[JustinBeckwith]

@alexander-fenster, @xiaozhenliu-gg5, @summer-ji-eng, @bcoe, @jkwlui did all the real work 🙃

[Fryuni]

@garyo did you open an issue about the missing compute documentation on google-api-nodejs-client? I'd like to follow that

[garyo]

Yes, it's googleapis/google-api-nodejs-client#1915 -- still open.

[garyo]

@JustinBeckwith wrote:

Greetings @garyo! That is the one module that likely won't be getting types 😬 I would highly recommend using https://github.com/googleapis/google-api-nodejs-client instead.

Just saw something you may find interesting: googleapis/nodejs-compute#534 -- It looks like it adds type decls to the compute module googleapis/nodejs-compute.

[moreiravictor]

How can I import types for cloud-vision? I can't find a way to do it. Seems it's all not exported :/

[JustinBeckwith]

@moreiravictor what have you tried?

[moreiravictor]

@JustinBeckwith tried importing it from @google-cloud/vision module