search

googleapis / google-cloud-node

Google Cloud Client Library for Node.js
https://cloud.google.com/nodejs
Apache License 2.0
2.91k stars 591 forks source link

TypeScript type definitions #952

Closed laurentgoudet closed 4 years ago

laurentgoudet commented 8 years ago

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

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 commented 8 years ago

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

:warning: 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.

:hourglass: 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.

:earth_americas: 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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

Thanks for sharing that!

the datastore api does seem a bit immature

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

JustinBeckwith commented 8 years ago

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: https://github.com/google/google-api-nodejs-client/issues/503

danvk commented 8 years ago

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

Splaktar commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

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 :+1: on this

lukesneeringer commented 7 years ago

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 commented 7 years ago

Adding my :thumbsup: to add Typescript defintion

afdalwahyu commented 7 years ago

btw, now you can install via npm: 

npm install --save-dev @types/google-cloud__storage
beaulac commented 7 years ago

Just submitted a PR.

Hopefully it's published soon 🤞

julien-c commented 7 years ago

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

beaulac commented 7 years ago

@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 commented 7 years ago

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

nbperry commented 7 years ago

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.

stephenplusplus commented 6 years ago

@lukesneeringer we know a lot more about our project now than we did in April-- we've relocated repos from the monorepo, introduced more GAPICs, and reached more GA's. Considering our course is getting more stable, is there any update for this issue?

DanielJoyce commented 6 years ago

Yes, very nice to have some sane code completion...

Why is this lagging so HARD, when https://github.com/google/google-api-nodejs-client has or will soon have typescript support? Why two seperate projects? What are the differences?

Seems the left and right hand at Google have no idea what each other is doing.

plaisted commented 6 years ago

This is the major holdup for us to adopt cloud functions into our tool set. Would love to hear some updates / plans on this.

Skwai commented 6 years ago

This prevented me from using TypeScript for my Firebase functions. The outdated definitions on definately typed were locked to GCF v1.1

kirillgroshkov commented 6 years ago

same for us!

nbperry commented 6 years ago

@Skwai @kirillgroshkov can you point me to these outdated definitions.

mattwelke commented 6 years ago

I came to this GitHub issue when looking into using TypeScript for the compute portion of the SDK. There's a comment above from quite a while ago where the user says the type package is @types/google-cloud__storage for Storage. I figured I would try installing @types/google-cloud__compute, but it failed, saying it couldn't be found. Is there no coverage of the Compute service for types right now? I only tried adding the types from DefinitelyTyped because I noticed after installing @google-cloud/compute that the types weren't included in that package.

nbperry commented 6 years ago

@welkie you are correct that to install the type definitions your looking for you would install @types/google-cloud__compute. Unfortunately there are no type definitions available for the compute API at this time via DefinitelyTyped.

mattwelke commented 6 years ago

@nbperry Gotcha. I imagine they want to wait until the API reaches 1.0.0+ before maintaining type definitions for it.

Are the developers behind the SDK welcoming PRs for type definitions in the NPM packages themselves?

nbperry commented 6 years ago

@welkie I am sure the developers would appreciate PRs. However I am unsure how they want the process for updating these as well as picking which version of each package to start supporting typescript definitions. By doing this it then becomes something they must maintain for each of the NPM packages themselves which could take a very large effort.

However you could definitely submit a PR for DefinitelyTyped and the process for this is pretty well defined here. My suggestion would be to create the definition you need here and submit it via a PR there, allowing the community to use these definitions immediately.

kirillgroshkov commented 6 years ago

@nbperry We're using these ones now (for Datastore): https://www.npmjs.com/package/@types/google-cloud__datastore

They're not bad. But it was very hard to find, and before we found them we almost created our own.

rivka-ungar commented 6 years ago

Are there type definitions available for google-cloud/translate?

JustinBeckwith commented 6 years ago

Yup!

chadbr commented 6 years ago

This is fantastic by the way -- !! Keep it up...

rivka-ungar commented 6 years ago

Great, Thanks! Where can I download?

JustinBeckwith commented 6 years ago

@rebeccau it's inside of the translate module. You don't need to install a types package :)

reconbot commented 6 years ago

Yes, everything here is an Apache 2.0 license

JustinBeckwith commented 5 years ago

Greetings folks! Little update. Spanner, PubSub, and Datastore recently landed types as well :)

kirillgroshkov commented 5 years ago

Greetings folks! Little update. Spanner, PubSub, and Datastore recently landed types as well :)

Did they? Doesn't work for me in Datastore, still relying on incompatible @types/google-cloud__datastore there ;-(

ps: sure, I can open an issue. I just didn't know they are supposed to work, so

JustinBeckwith commented 5 years ago

@kirillgroshkov they should work :) Please open an issue over in https://github.com/googleapis/nodejs-datastore/ if they're not!

MagsMagnoli commented 5 years ago

@laurentgoudet please add dialogflow to this list!

csidell-earny commented 5 years ago

Hope bigtable is included soon

IchordeDionysos commented 5 years ago

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 commented 5 years ago

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

bcoe commented 5 years ago

@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 commented 4 years ago

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