I’ve forked and made minor pull requests in the past, but this past week (a full 3 days of analyzing/coding & 1 day of documentation), I made my first real fork of an existing project. It was quite the task as I had to learn the ins and outs of the existing codebase in order to make the large changes I wanted. Today, I’ll be talking about my entire thought process as I forked google-maps-services-js into react-native-google-maps-services.

Motivations

I wanted to use the Google Places API, specifically Nearby Search, in the React Native app that I’ve been building and mentioning in my devlogs. The problem was that I was unable to find a satisfactory client library to use (something I’ll talk about later). So, I was left with the choice of either writing one from scratch or forking an existing repository and changing it to suit my needs. In the spirit of open source, I decided that forking was the way to go (it’s also a lot less work ;).

Background: The API

When people talk about Google Places API, there are actually several different parts to the API serving different functionality. This can get confusing when you search for information on how to use the API as you can get conflicting information as each has somewhat different functionality. It also gets very annoying when looking for client libraries as all of them use a generic name of “Google Places” but are actually built for only some of the APIs.

On top of that, the Places API is a subset of the APIs groups under the Google Maps API name. This can cause a lot of confusion when looking for information on how to use the different libraries.

Then on top of that, there are slightly different APIs exposed by the Android and iOS libraries. Both of which can be accessed by React Native if you choose to go the native module route.

Lastly, on top of that(!), there are different APIs exposed by the Places Library in Maps JavaScript API and others. There’s a lot to dig through and it’s made all the more confusing by the reuse of names. For my purposes, I’ll only dive into the web services APIs and a bit into the mobile APIs.

Google Maps API Hierarchy for Web Services

• Google Maps API - No actual APIs. It’s just a name.
  • Access HTTP interfaces, providing geographic data such as geocoding, directions, elevation, place and time zone information.
  • Geocoding
    • Convert between addresses and geographic coordinates.
    • Has both geocoding and reverse geocoding.
  • Google Places API - No actual APIs. It’s just a name.
    • Implement autocomplete and add up-to-date information about millions of locations to your site or app.
    • Places Search
      • Return a list of places based on a user’s location or search string.
    • Nearby Search
      • A Nearby Search lets you search for places within a specified area. You can refine your search request by supplying keywords or specifying the type of place you are searching for.
    • Text Search
      • The Google Places API Text Search Service is a web service that returns information about a set of places based on a string.
      • The service is especially useful for making ambiguous address queries in an automated system, and non-address components of the string may match businesses as well as addresses.
    • Radar Search
      • The Google Places API Radar Search Service allows you to search for up to 200 places at once, but with less detail than is typically returned from a Text Search or Nearby Search request.
      • This is deprecated as of June 30, 2017 and will be removed as of June 30, 2018.
    • Place Details
      • Requests return more detailed information about a specific Place, including user reviews.
    • Place Add
      • Allow you to supplement the data in Google’s Places database with data from your application.
      • This is deprecated as of June 30, 2017 and will be removed as of June 30, 2018.
    • Place Photos
      • Gives you access to the millions of Place related photos stored in Google’s Place database.
    • Place Autocomplete
      • Can be used to automatically fill in the name and/or address of a place as you type.
      • This is limited to 5 results per query. See the bottom of responses section of the docs. It actually used to be up to 20 with pagination, but it has long since been changed.
    • Query Autocomplete
      • Can be used to provide a query prediction service for text-based geographic searches, by returning suggested queries as you type.
  • Elevation
    • Elevation data for any point in the world.
  • Google Maps Roads API - No actual APIs. It’s just a name.
    • Enable snap-to-road functionality to accurately trace GPS breadcrumbs.
    • Snap to Roads
      • The Google Maps Roads API takes up to 100 GPS points collected along a route, and returns a similar set of data, with the points snapped to the most likely roads the vehicle was traveling along. Optionally, you can request that the points be interpolated, resulting in a path that smoothly follows the geometry of the road.
    • Nearest Roads
      • The Google Maps Roads API takes takes up to 100 independent coordinates, and returns the closest road segment for each point. The points passed do not need to be part of a continuous path.
      • If you are working with sequential GPS points, use Snap to Roads.
    • Speed limits
      • The Google Maps Roads API returns the posted speed limit for a given road segment. In the case of road segments with variable speed limits, the default speed limit for the segment is returned.
  • Geolocation
    • Find a location based on information from cell towers and WiFi nodes.
  • Directions
    • Calculate directions among multiple locations.
  • Time Zone
    • Provide time zone data for anywhere in the world.
  • Distance Matrix
    • Estimate travel time and distance for multiple destinations.

Important Notes

• Usage Limits and Pricing for the Google Maps API looks to be all under the same hood. So if you are using several of the services, understand that your queries are all counted in aggregate.
• You must show attribution somehow if you use Google Maps APIs. You need to either:
  • Have some sort of “Powered by Google” logo under the results, or
  • display the results in conjunction with Google Maps (which itself has the logo).

Looking for a Client Library

This was a multi-day effort of reading docs, diving into source code for poorly documented projects, and testing integration with React Native. This is what I discovered:

• Official Client Libraries exist for Java, Python, Go, and Node.js.

  • I tried using the Node.js one (google-maps-services-js) for React Native, but alas, even with shims and installing the correct libraries, it doesn’t work. A short list of the issues I ran into:
    • Documentation that is so poor that it borders on willful ignorance.
    • Exceptions being swallowed making it impossible to actually debug.
    • Vague errors like timeout that mean nothing.

  • If you want to try installing it into React Native, you can use the following libraries to get access to the Node.js core libraries (required since they aren’t part of React Native’s JavaScript engine; see also):

    1. node-libs-react-native for React Native specific alternatives to the core in a single package.
       • Take note of the globals export needed to simulate the globals in Node.js.
    2. node-libs-browser for general browser alternatives to the core in a single package.
    3. Manually creating and using core Node.js Modules in React Native. I didn’t try this due to bloat one but it should work.

    4. Installing the individual core libraries needed and using babel-plugin-rewrite-require to transform the requires that don’t have direct naming equivalents. And you’ll also have to install the q promise library for JavaScript as that is used in the code but no error is thrown when it isn’t found. Here’s an example of what you can put into your .babelrc:

       1 2 3 4 5 6 7 8 91011121314

       "plugins": [ [ "babel-plugin-rewrite-require", { "aliases": { "crypto": "crypto-browserify", "https": "https-browserify", "http": "stream-http", "stream": "readable-stream", "vm": "vm-browserify" } } ] ],

  • The core bug is this:

    • YellowBox.js:82 Possible Unhandled Promise Rejection (id: 0):
    • TypeError: Cannot read property 'getReader' of undefined
    • I believe that the core issue is React Native’s lack of streaming support for http(s) requests. See also this similar issue. (See a few points further down.)
      • And this definitely works outside of React Native as seen here.
      • Also note that it’s part of the whatwg/streams library.
      • This could be a possible patch fix: Fix readable-stream in React Native
      • I’ve already tried these libraries:
        • fetch-readablestream
        • stream-http
        • readable-stream
        • react-native-http
        • https-browserify
    • So I figured out exactly where the error is. Inside the stream-http library in lib/response.js at line 72, it attempts to use response.body’s getReader() method. However, there is no body property of the response. The question is why? There is a response with data. Just no body (undefined).
    • The Investigation:
      • React Native’s fetch implementation lags behind the official as can be seen by the dependencies:
        • "whatwg-fetch": "^1.0.0",
        • "node-fetch": "^1.3.3",
        • whatwg-fetch lags behind the current release of whatwg-fetch (2.0.3).
      • This is one possible source of bugs, but that’s probably not the only issue as I did force fetch to be replaced by whatwg-fetch by doing:
        • yarn add whatwg-fetch
        • Edit whatwg-fetch’s source code to not check for self.fetch (fetch.js line 4)
        • This will cause RN to choose whatwg-fetch. Previously, it didn’t because that check prevented whatwg-fetch from replacing the native fetch call. Which conflicts with how RN is checking for whatwg-fetch (react-native/Libraries/Network/fetch.js and react-native/Libraries/Core/Devtools/symbolicateStackTrace.js). Yay for conflicting code bases!
      • The result was no change as body remained undefined.
      • So digging deeper and debugging the various code bases more, I found that:
        1. What the code is trying to do is get a stream from the fetch response’s body.
        2. This body attribute of response is from the whatwg spec for streams.
           • This current spec has long since solidified support for streams in fetch. [1] [2]
        3. React Native is not up to date with the current whatwg spec for streams as evidenced by:
           • This long standing Canny feature request: Fetch Streaming Body
           • Original bug issue #9629.
           • Related bug issue #12912
        4. So fetch streams are flat out broken in React Native.
        5. But ignoring that, Google is also messing up here. They are sending GET requests and expecting a readable stream to come back in the body of the response. This is not per spec as HEAD or GET requests should never have a body!
      • The result of my code dive is that both React Native and Google have screwed up here! No amount of shimming will fix this issue as it would just cause a lot more problems down the road.
      • Instead, if you want to use this client library, the best solution is to fork Google’s library and avoid using Node.js core modules like HTTP/HTTPS as they will inevitably run into compatibility and support issues down the line. Reimplementing with a dedicated request library like axios or superagent would yield more stable results on React Native. These projects will be much more platform agnostic and be more responsive to fixing issues related to the spec.

• react-native-google-places-autocomplete

  • This is a React Native component that only implements these APIs:
    • Nearby Search
    • Geocoding
  • As a component, it’s not easy to customize the behavior. It also doesn’t work well when nested in any scrolling type view because of the nested ScrollView bug in React Native.
  • It does not expose an API for you to use to drive your own components.
  • The list of features is quite nice so it could be a good base to create your own generic API.

• react-native-google-places

  • This is a React Native component and API library.
  • The API library exposes these APIs from the Android and iOS libraries:
    • Place Autocomplete
    • Place IDs and Details
    • Current Place
  • The component is a native modal-like component. It is not customizable.
  • The exposed APIs are extremely limited and it’s clear that this native module is built to satisfy a very specific use case. So while nicely built, it is unlikely that this would be the perfect fit for you.
  • The code quality is high though, so it could be a good base for building out a more complete/comprehensive native module.

• googleplaces.js

  • Node.js library that supports these APIs (source code for better documentation):
    • Place Search
    • Place Details
    • Place Autocomplete
    • Events (aka: Place Add)
  • The downsides to this library are that:
    • it won’t work on React Native unless you start shimming in all the core Node.js libraries, and
    • it’s not maintained very actively (ex: no license).

• googleplaces-promises

  • This is the same as the googleplaces.js library but with a wrapper (via q promise library) to make it so it works with ES6 promises.

• google-places-browser

  • Wraps the Google Maps JavaScript API in Node-style callbacks.
  • This is what I meant by Google reusing names everywhere causing tons of confusion when searching for client libraries.

• node-google-places

  • Very simple library for the Places API. It only exposes:
    • Search - This has long since been deprecated and broken up into the three APIs listed above.
    • Autocomplete
    • Details
  • It is unmaintained and hasn’t been updated for years.

• node-googleplaces

  • Very simple library for the Places API. It exposes all of the sub-APIs.
  • It leverages the superagent library to handle HTTP requests instead of the core Node.js http/https libraries.
  • This hasn’t been maintained for years.
  • Although old, it’s an example of what I’d probably do if I implemented my own generic API - use something like axios to do all of the calls.

Conclusion

Nothing works.

• There’s only one library that covers all Google Maps APIs and that is Google’s official Node.js library. However, even with the massive dependency bloat and shimming required to use core Node.js modules in React Native, it does not work.
• All other libraries fall short and are often very use case specific.

Exploring All Options

Before going down the route of writing or forking a client library, it’s prudent to examine your original project needs to see if this is the best use of your time. And so, that’s what I did.

Alternatives to Google

Some suggestions and comparisons to read:

• What is a good, unlimited alternative to Google Places API?
• Are there alternatives to the Google Places API, for lat/long retrieval?
• What are the pros and cons of each ‘places’ API, ie. Foursquare versus Google?

These are the best of the best. Foursquare is the most attractive offering. Mapbox is great too as it would just be a part of their total offering (you can maybe even remove Google Maps completely). Agolia is a big name, but I’d rather go with Foursquare if I weren’t to try and use a completely Mapbox-only solution. Lastly, OSM is included because it’s the one self-hostable solution.

1. Foursquare
   • They seem to be the largest consensus provider that is used by notable companies like Instagram.
   • Like Google, they named it Places API. It has very comparable functionality.
   • Their docs are also quite clean.
   • They have no official libraries, but you can build one and submit it to them to be listed on their website.
     • node-foursquare
     • react-foursquare
2. Agolia Places
   • It too uses the same naming and provides a lot of the same functionality as Google.
3. Mapbox
   • Geocoding Service (aka: Search)
   • Directions Service (aka: Navigation)
     • Has several sub-APIs like Google.
   • Maps Service (aka: Maps)
     • Their core offering - vector maps. An alternative to Google Maps.
   • Mapbox Studio
     • For creating custom maps.
   • Customer Showcase to show what can be done with their APIs:
     • Store locator
     • Turn-by-turn navigation
     • On‑demand logistics
     • Data visualization
     • Asset tracking
4. Nominatim
   • This is the OpenStreetMaps API.
   • You can actually download all the OSM data and setup a server yourself that allows for geocoding and reverse geocoding. It’s quite a heavy process though so rarely worth it.

Conclusion

While these certainly do provide APIs that have the functionality I desire, none have an official React Native client library. Foursquare comes the closest but the libraries do not look very well maintained. As such, I felt that my time was better spent going with Google for now as it has the most robust looking code base for me to work off of.

If in the future I decide that I want to remove all Google services, I can probably reuse what I’ve learned from their codebase to write a more robust client library for Foursquare/Mapbox/etc.

Forking

With that out of the way, I made my decision to fork google-maps-services-js. I had to fork because:

• I wanted to remove as many core Node.js module dependencies as possible. The ultimate goal being to use the library in React Native without having to shim in any code.
  • One suggestion seen in the issues is to use a custom makeUrlRequest (#88 [#64(https://github.com/googlemaps/google-maps-services-js/issues/64)]). However, this wouldn’t work because we wouldn’t be able to remove the dependency on url. It would also be more difficult to differentiate between put and get requests because of how the architecture of the code makes assumptions in makeApiCall based on where it places value.
• I wanted to make custom makeUrlRequests even easier to create. This would allow swapping out axios much easier in the future. Passing around the config options in a sensible manner and making them available for assembly in the request.
  • Note the downside: This is less optimized because of the greater overhead of parsing the options and constructing the url every time a request is made. This could have been alleviated by creating an axios instance in place of requestUrl in makeApiCall, but it would remove the ability to swap out backends. I am also unsure of how reusing axios instances behave.
• I also wanted to pick a backend that had the fewest dependencies to reduce bloat when used with React Native due to it being a mobile framework. Of the HTTP clients I evaluated - axios, superagent, request, got - axios looked to pull in the fewest dependencies. It also is written in promise style (my preference) and is the most popular. So it was an easy choice.

Given that rationale, it was an easy decision to make. Furthermore, Github makes forking so easy that it seemed like a no brainer over trying to write from the ground up. Do keep in mind that while you work on your fork, the upstream repository may get some commits pulled in that you need to merge into your fork. I found these guides to be the most useful in understanding how to do this and how to write my commit messages:

• Merging an upstream repository into your fork
• Addressing merge conflicts
• Autolinked references and URLs

Source Code Deep Dive

These are the parts of the google-maps-services-js source that use core Node.js modules:

• google-maps-services-js/lib/index.js
  • Uses util.deprecate() to mark deprecated API methods.
• google-maps-services-js/lib/internal/cli.js
  • Uses Process to parse args.
• google-maps-services-js/lib/internal/make-api-call.js
  • Uses Url used to create the URL to send and to generate an encrypted signature.
    • Specifically, formatRequestUrl() - url.format & url.parse.
  • Uses Process to grab environment variables.
  • Uses setTimeout and clearTimeout as default fallbacks.
  • Uses Buffer to help generate the client secret.
    • Specifically, look at formatRequestUrl() and computeSignature().
  • Uses crypto in conjunction with Buffer to create an encoded signature.
  • Uses encodeURIComponent to encode the signature.
• google-maps-services-js/lib/internal/make-url-request.js
  • Uses https uses to make a request.
    • This is probably where axios should come in.
  • Uses https.Agent to set keep-alive to true.
  • Uses Url’s parse to parse the URL’s requestOptions.
  • Uses Buffer in conjunction with https’s chunking ability to grab the response in pieces.
  • NOTE: Making the https.request is the root call that leads to the eventual body is undefined error.
• google-maps-services-js/lib/internal/task.js
  • Their complicated system for rate management on the client side is what causes the library to not work (is my guess). It’s not. Nothing else to edit here.
  • Uses Process.nextTick to ensure the queued task will run in the next event loop.
• google-maps-services-js/lib/internal/wait.js
  • Uses setTimeout() for each task that is executed.
  • Uses clearTimeout() for cancelling tasks.

These will all have to be swapped out and replaced with a library like axios or superagent. A lot of the interface code, validation code, and even parts of the client side rate limiting should be reusable and remain untouched if done right.

Worklog: Rewriting with axios

Using my deep dive notes, I went through each task systematically to make sure that I didn’t miss anything that needed editing. Checklists for the win! You can follow along with my notes below as I explain the rationale behind all of my code edits.

• google-maps-services-js/lib/index.js
  • Uses util.deprecate() to mark deprecated API methods.
    • This doesn’t add any functionality other than telling users that something is deprecated. For this fork, I’ll just remove it and any deprecated APIs will just be unavailable unless directly accessed via hard coded imports.
    • Other options include:
      • A browserified version of the deprecate function: util-deprecate. I chose not to use this because there’s really no point and for mobile apps, you want to keep dependencies low.
      • Porting the code myself: node/deprecate.js. While it’s not long and probably not too hard, I’d rather not go through the trouble for now.
      • Writing a simple wrapper that prints a console.warn with the deprecation method but otherwise does nothing else. This is feasible, but if I do it, it will be in a later commit.
• google-maps-services-js/lib/internal/cli.js
  • Uses Process to parse args.
    • For a React Native module, we don’t need a command line interface. so I ripped out cli.js and run.js.
• google-maps-services-js/lib/internal/make-api-call.js
  • Other edits made so I could use axios:
    • Added method to the queryOptions to be later used in make-url-request. This is either POST (explicit) or GET (implicit default) based on how they wrote their definitions.
    • I had to modify the rask race code to change response.requestUrl to equal requestUrlConfig as we no longer create a url.
      • NOTE: This is a potential place for bugs as I did not check the task code to see how it compares and looks up what has been queued/run.
  • Uses Url used to create the URL to send and to generate an encrypted signature.
    • Specifically, formatRequestUrl() - url.format & url.parse.
      • I removed all of this. They were used for two reasons:
        • To generate the full url + query string to be later used by https.request.
          • With axios, this full string is not needed as the library will handle it for you. In place of this, I put all of the code into a params object that I returned to be later used by makeUrlRequest to create the axios instance.
        • To generate a path + query string that is used when useClientId is true to create a encoded signature that is appended onto the end of your query string.
          • To accomplish this, I edited all of the lib/apis files to have baseURL and relativeURL params. This made it so I could use encodeURIComponent to manually build the path + query string needed to do the encode.
          • NOTE: This is one potential area for a bug as url.format followed the WHATWG URL spec which looks to do quite a bit more than just encode. You can confirm this by seeing the extra cases that were discussed in this bug report: #1802. Then compare to how encodeURIComponent works: [1] [2] [3] [4]
      • I declined to add extra dependencies on libraries like node-url, url-parse, querystring, whatwg-url, and qs for a variety of reasons. Foremost being dependency bloat and the potential for them to still require other core Node.js libraries. Other reasons: #33 #20
      • I also declined to use fetch because my experience with it in React Native has shown it to be very lacking. For example: #256 and that abort/cancel is still not finished (something needed by this codebase).
  • Uses Process to grab environment variables.
    • Leaving this in, but it will not work. React Native only has process.env.NODE_ENV which is shimmed in for compatibility purposes.
    • This is left in in case a user wants to use 12 factor via something like react-native-config.
    • For additional details and alternatives to using environment variables in React Native, see: Setting environment variable in react-native?
  • Uses setTimeout and clearTimeout as default fallbacks.
    • These globals are included in React Native. No change needed.
  • Uses Buffer to help generate the client secret.
    • Specifically, look at formatRequestUrl() and computeSignature().
      • Added buffer as a dependency and imported it in this file per the suggestion from the official RN bug tracker since it’s the only place it’s used.
      • There really is no alternative as buffer is the best way to handle binary data in JavaScript. React Native appears to have a suboptimal implementation for anything related to this. See #10 in 10 Things you should know about React Native.
  • Uses crypto in conjunction with Buffer to create an encoded signature.
    • Added crypto-js as a dependency which should work as it’s a pure JS implementation of crypto libraries.
    • Then rewrote the code with the equivalent implementation based on docs and this example showing a comparison and making sure not to make the same mistake as seen in this StackOverflow question.
    • I also had to use toString() on the payload and secret for some reason as I was running into this bug: #32
    • react-native-crypto is also an alternative but would cause a lot more bloat as you still need shimming and lot of core Node.js modules.
  • Uses encodeURIComponent to encode the signature.
    • This global exists on React Native. No change needed.
• google-maps-services-js/lib/internal/make-url-request.js
  • Uses https uses to make a request.
    • This is probably where axios should come in.
    • I modified the function signature to expect the config object that I created using edits to the lib/apis files and the return from formatRequestUrl.
    • I then modified the code to build up a full configuration of options that are then passed to axios.create in order to create an instance that will later send the request out.
    • For the request itself, I converted the callback style code to promises.
    • I removed the 302 redirect retry if block because axios automatically follows redirects.
    • I removed chunking as explained in the Buffer point below.
    • For the return, it uses axios.cancel with a generic cancellation message.
    • NOTE: Parsing through the options and handling the header code is a potential place for bugs as I was not able to check for every possible option in the docs as there are no docs for usage in this library.
  • Uses https.Agent to set keep-alive to true.
    • I set the axios header for Connection to keep-alive which possibly does the same thing. However…
    • NOTE: The config documentation shows httpAgent and httpsAgent params that take the very http/https object that I removed. So this probably does not work as I expect.
  • Uses Url’s parse to parse the URL’s requestOptions.
    • axios.create() should build an instance with the correct default headers (and other params). So manually creating those params via Url’s parse shouldn’t be needed.
    • NOTE: I am unfamiliar with the specifics of how url.parse works at the low level, so my assumption above could be incorrect. A bug with the headers could have been introduced here. I may also need to use another library to have a keep-alive agent as suggested by the answers here.
  • Uses Buffer in conjunction with https’s chunking ability to grab the response in pieces.
    • This was removed because streaming requests are not yet supported in axios. See: #479 #484 #1072
    • If axios ever supports this again, it should be relatively easy to add chunking back in for faster responses.
  • NOTE: Making the https.request is the root call that leads to the eventual body is undefined error.
    • This is the root call the eventually leads to the broken code (body is undefined in the http response due to the lack of streaming support). This is “fixed” by replacing https/http with axios.
• google-maps-services-js/lib/internal/task.js
  • Their complicated system for rate management on the client side is what causes the library to not work (is my guess). It’s not. Nothing else to edit here.
  • Uses Process.nextTick to ensure the queued task will run in the next event loop.
    • Use setImmediate instead on React Native.
    • NOTE: There is a difference between the two so I’m not sure if I’ll be introducing a bug here. See: setImmediate vs nextTick and The Node.js Event Loop, Timers, and process.nextTick()
      • LATER NOTE: Yes, this did introduce a bug which can be seen in the testing section.
• google-maps-services-js/lib/internal/wait.js
  • Uses setTimeout() for each task that is executed.
  • Uses clearTimeout() for cancelling tasks.
    • Both of these are actually function params. They get their global equivalents via default props if not set by the user. Both of which are available in React Native.

End Result

Showing 15 changed files with 92 additions and 160 deletions.

Explicit Dependencies Added:

• buffer
• crypto-js
• axios

Running Tests

React Native

Writing up some test code and putting the API through its paces in React Native showed that everything worked! Except geolocate… why?

It turns out that geolocate is no longer functional due to these outstanding issues/PR in axios: #723 #1342 #1121. Tracing the code all the way back, it looks like this bug was introduced in a combination of this commit and this commit that eventually changed the merge order of precedence like so:

1. get default < config
2. this.defaultConfig < get default < config
3. defaults < this.defaults < get default < config

So it was a consequence of not thinking through the history of changes and how axios recommends editing configs. The PR should fix this by changing the order to this:

• defaults < get default < this.defaults < config

For now, all I can do is wait to bump the axios version one the fix is merged and released.

Spec Tests

Running the tests showed that some specs are failing. Meanwhile, all of Google’s spec tests pass.

My Spec Test Results

  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99100101102103104105106107108109110111112113114115116117118119

npm test

> @google/maps@0.4.5 test /Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js
> jasmine && jasmine spec/e2e/*.js

Started
......F.............FFFF....F................................FFF.................

Failures:
1) attempt (when the second attempt succeeds) calls the callback with the successful result
  Message:
    Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.
  Stack:
    Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.
        at ontimeout (timers.js:469:11)
        at tryOnTimeout (timers.js:304:5)
        at Timer.listOnTimeout (timers.js:264:5)

2) index.js: using a client ID and secret generates a signature param
  Message:
    Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.
  Stack:
    Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.
        at ontimeout (timers.js:469:11)
        at tryOnTimeout (timers.js:304:5)
        at Timer.listOnTimeout (timers.js:264:5)

3) index.js: using a client ID and secret includes the channel if specified
  Message:
    Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.
  Stack:
    Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.
        at ontimeout (timers.js:469:11)
        at tryOnTimeout (timers.js:304:5)
        at Timer.listOnTimeout (timers.js:264:5)

4) index.js: using a language param can set the language per client
  Message:
    Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.
  Stack:
    Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.
        at ontimeout (timers.js:469:11)
        at tryOnTimeout (timers.js:304:5)
        at Timer.listOnTimeout (timers.js:264:5)

5) index.js: using a language param can override the language per method
  Message:
    Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.
  Stack:
    Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.
        at ontimeout (timers.js:469:11)
        at tryOnTimeout (timers.js:304:5)
        at Timer.listOnTimeout (timers.js:264:5)

6) index.js: throttling spaces out requests made too close
  Message:
    Expected [ 0, 0, 60000 ] to equal [ 0, 0, 0, 30 ].
  Stack:
    Error: Expected [ 0, 0, 60000 ] to equal [ 0, 0, 0, 30 ].
        at /Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js/spec/unit/index-spec.js:210:30
        at /Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js/lib/internal/make-api-call.js:150:29
        at Immediate.<anonymous> (/Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js/lib/internal/task.js:247:27)
        at runCallback (timers.js:781:20)

7) throttle doesn't wait when calls are made far apart
  Message:
    Expected 1002000 to be 2000.
  Stack:
    Error: Expected 1002000 to be 2000.
        at /Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js/spec/unit/throttled-queue-spec.js:152:33
        at Immediate.<anonymous> (/Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js/lib/internal/task.js:238:27)
        at runCallback (timers.js:781:20)
        at tryOnImmediate (timers.js:743:5)

8) throttle does not wait for calls that are cancelled
  Message:
    Expected 1000000 to be 0.
  Stack:
    Error: Expected 1000000 to be 0.
        at /Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js/spec/unit/throttled-queue-spec.js:165:31
        at Immediate.<anonymous> (/Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js/lib/internal/task.js:238:27)
        at runCallback (timers.js:781:20)
        at tryOnImmediate (timers.js:743:5)
  Message:
    Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.
  Stack:
    Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.
        at ontimeout (timers.js:469:11)
        at tryOnTimeout (timers.js:304:5)
        at Timer.listOnTimeout (timers.js:264:5)

9) throttle when limit is 3 waits before making the 4th call made together
  Message:
    Expected 1000000 to be 0.
  Stack:
    Error: Expected 1000000 to be 0.
        at /Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js/spec/unit/throttled-queue-spec.js:201:33
        at Immediate.<anonymous> (/Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js/lib/internal/task.js:238:27)
        at runCallback (timers.js:781:20)
        at tryOnImmediate (timers.js:743:5)
  Message:
    Expected 1000000 to be 0.
  Stack:
    Error: Expected 1000000 to be 0.
        at /Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js/spec/unit/throttled-queue-spec.js:206:33
        at Immediate.<anonymous> (/Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js/lib/internal/task.js:238:27)
        at runCallback (timers.js:781:20)
        at tryOnImmediate (timers.js:743:5)
  Message:
    Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.
  Stack:
    Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.
        at ontimeout (timers.js:469:11)
        at tryOnTimeout (timers.js:304:5)
        at Timer.listOnTimeout (timers.js:264:5)

81 specs, 9 failures
Finished in 35.193 seconds
npm ERR! Test failed.  See above for more details.

So why is this the case? My initial guess was that this had to do with using setImmediate as the tests had to do with timing and task.js. A quick edit of the original source to setImmediate and a run later showed this to be partially the case:

 1 2 3 4 5 6 7 8 9101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657

npm test

> @google/maps@0.4.5 test /Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js-original
> jasmine && jasmine spec/e2e/*.js

Started
............................F.......................F..........F.................

Failures:
1) index.js: throttling spaces out requests made too close
  Message:
    Expected [ 0, 0, 0 ] to equal [ 0, 0, 0, 30 ].
  Stack:
    Error: Expected [ 0, 0, 0 ] to equal [ 0, 0, 0, 30 ].
        at /Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js-original/spec/unit/index-spec.js:210:30
        at /Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js-original/lib/internal/make-api-call.js:146:29
        at /Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js-original/lib/internal/task.js:247:27
        at _combinedTickCallback (internal/process/next_tick.js:131:7)

2) Task.race cancels the second task if the first task finishes
  Message:
    Expected spy cancelled2 to have been called.
  Stack:
    Error: Expected spy cancelled2 to have been called.
        at /Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js-original/spec/unit/task-spec.js:206:26
        at /Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js-original/lib/internal/task.js:238:27
        at _combinedTickCallback (internal/process/next_tick.js:131:7)
        at process._tickCallback (internal/process/next_tick.js:180:9)

3) throttle when limit is 3 waits before making the 4th call made together
  Message:
    Expected 1000000 to be 0.
  Stack:
    Error: Expected 1000000 to be 0.
        at /Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js-original/spec/unit/throttled-queue-spec.js:201:33
        at /Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js-original/lib/internal/task.js:238:27
        at _combinedTickCallback (internal/process/next_tick.js:131:7)
        at process._tickCallback (internal/process/next_tick.js:180:9)
  Message:
    Expected 1000000 to be 0.
  Stack:
    Error: Expected 1000000 to be 0.
        at /Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js-original/spec/unit/throttled-queue-spec.js:206:33
        at /Users/mike/WorkspaceOSS/ReactNative/google-maps-services-js-original/lib/internal/task.js:238:27
        at _combinedTickCallback (internal/process/next_tick.js:131:7)
        at process._tickCallback (internal/process/next_tick.js:180:9)
  Message:
    Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.
  Stack:
    Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.
        at ontimeout (timers.js:469:11)
        at tryOnTimeout (timers.js:304:5)
        at Timer.listOnTimeout (timers.js:264:5)

81 specs, 3 failures
Finished in 5.147 seconds
npm ERR! Test failed.  See above for more details.

So for comparison, that’s this difference which doesn’t align perfectly:

12345

# My Fork
......F.............FFFF....F................................FFF.................

# Google
............................F.......................F..........F.................

This is an oddity that is going to require a lot more investigation.

End-to-End Tests

For the e2e tests, you’ll find that Google has not updated this library in a long time as the majority of their tests fail. When compared to my fork, you’ll actually get the same errors (+1 for removing the deprecated method):

 1 2 3 4 5 6 7 8 9101112

....FFFFFFFFFF.FFFFFFF(node:44556) DeprecationWarning: placesRadar is deprecated, see http://goo.gl/BGiumE
.F...FFFFFFF

# Cutting out the deprecated test results in:
....FFFFFFFFFF.FFFFFFF.F...FFFFFFF
34 specs, 25 failures
Finished in 85.355 seconds

# Which you can compare to the rewrite that results in:
....FFFFFFFFFF.FFFFFFFFF...FFFFFFF
34 specs, 26 failures
Finished in 83.239 seconds

I’m not sure how I’ll be tackling these errors as I have no passing baseline to compare against.

Result: Usable But Needs Work

Overall, I would say that while work still needs to tbe done, the code is at least usable for my current purposes. If you would like to use this, be aware of the work I’ll be tackling in Future Tasks.

Now to make this fork usable by others without clashing with the original, I had to rename it on Github:

• Renaming a repository
• Update package.json with the correct new information.
• Bump the version and tag a new release so it doesn’t conflict with the original source repository’s releases.

Then publish it on npm with the new name:

• How to Publish & Update a Package

And voila! You can now install and use this package with:

1

yarn add react-native-google-maps-services

But a disclaimer: There are lots of outstanding issues that I need to fix before tagging this with a production ready release. So use this at your own risk!!

Legal Stuff & Etiquette

Forking an publishing projects under a new name isn’t all that simple though. There’s a lot of legal stuff and etiquette that I had to read up on first before I was sure that I should/can do this. IANAL but I’m pretty sure that the Apache 2.0 license that Google uses is ok with this given a bunch of caveats that I have to follow: [1] [2]

Also, remember that you’re building on the shoulders of giants when you fork and use open source work. Do your best to give back, but also be free to build on top of prior with with proper accreditation of course! [1] [2]

Future Tasks

You can check the README for a list of immediate tasks that I’ll be tackling. However, in addition to those, I am also considering the following:

• Simple deprecate warn wrapper so I can add back in placesRadar support so it can at least be used until it’s fully turned off.
• Much better documentation so people don’t have to dig into the docs like I did to figure out how to use it for anything beyond the simplest of tasks.
• Advanced usage documentation that explains how you can use custom configs like makeUrlRequest.
• React Native specific examples.
• Custom pure components showcasing the usage of this library.

There’s more that can also be done like using it with React, Angular, etc. I’ve also run into some interesting articles on what you can do when implementing the Google Maps APIs. They’re good source for looking at features can be added after exposing the APIs themselves:

• React Native: Maps with Direction From Current Location (Dec. 04, 2017)
• IMPLEMENTING GOOGLE PLACES AUTOCOMPLETE WITH ES6 - PART THREE (Feb. 08, 2017)
• How I (sort of) got around the Google Maps API results limit (Oct. 21, 2016)
• A new kind of map: it’s about time (Points of Interest Map using Mapbox)

However, all of these extras are outside of my skillset and the current scope of the project. They’re all fun things to think about and hopefully I can tackle them in the future. On that note, I’ll end this post by saying that my first foray into open source has been super fun!

Copyright © 2011-2020 Ho Yin Cheng