Common interface for admin & regular SDKs?

[charles-allen]

TL;DR: substitutability of the 2 Firebase JS SDKs would be valuable for JS/TS monorepos

I noticed the Firebase team is doing a major refactor to make the Firebase SDK treeshakable. This might be the best opportunity to align the 2 JS SDKs, so I thought I'd throw the idea out... Can the types be moved up to a shared package, which both SDKs implement?

Motivation

Most of my projects have 3 frontend modules & 1 shared module:

• admin (CLI)
• functions (API)
• hosting (clientside web)
• common (shared code)

I have a Dao package in common. My dao objects depend on firestore. However, my various frontends use different versions of the Firebase SDK:

• admin -> firebase-admin
• functions -> firebase-admin
• hosting -> firebase

The 2 SDKs (at least for firestore) are very nearly aligned, but not quite. In fact I can attest to how similar they are; blindly type asserting that the admin SDK is the client SDK appears to be "working" within my project (I realise this is not sensible -- hence this suggestion to do it properly).

Concept (arrow = depends on)

// sdk
firebase -> firebase-types
firebase-admin -> firebase-types

// projects
common -> firebase-types
hosting -> common, firebase
functions -> common, firebase-admin
admin -> common, firebase-admin

Incremental

If desired, I think this could be built product-by-product, eg. starting by only extracting Firestore types. I picked Firestore because I already have a use case in my projects. Though I'm also starting to see the same for Storage & probably the issue is general.

Exclusions

I am not suggesting interoperability between the 2 SDKs. I would not expect necessarily, for example, that the admin-SDK implementation of FieldValue should work with a client-SDK query.

I'm only suggesting that the API surface expose the same types, so that I could inject either implementation (not both together) into my common code.

fingers crossed

[Feiyang1]

Have you tried typesaurus? It seems to solve your use case where you want to share code between server and client.

The admin SDK is unlikely to adopt the same API as the new client SDK, because size is not a concern on server side and we don't want to sacrifice usability (e.g. method chaining) for no benefits. So I think it will be hard to share types between the 2 SDKs as their APIs diverge. At the moment, I think your best bet is use third party solutions built on top of firebase SDKs, like typesaurus.

[charles-allen]

I haven't tried typesaurus, and I definitely will! Thank you.

But at the same time, I don't think the presence of a 3rd-party wrapper solution should write-off improving the SDKs themselves, so I'd like to keep the discussion open. I appreciate that this probably isn't high priority & it isn't going to happen overnight. My goal is that the team have this in the back of their minds so that you're moving towards it rather than away.

Contradictory divergence is undesirable

I think it will be hard to share types between the 2 SDKs as their APIs diverge

I would argue that any divergence that causes contradiction is undesirable. Both SDKs are backed by the same product(s). It's the product that defines the overall API, not the SDK. The SDK just defines the accessible subset & the syntax; subsetting is fine with types and I don't see a good argument for arbitrarily different syntax.

Standardizing types actually improves usability

we don't want to sacrifice usability

Your argument seems to be that this would restrict the admin SDK. I don't believe that's true.

I'm suggesting both SDKs extend (subtype) the same common types. The admin SDK would be free to support as many additional features as you like; this proposal merely forces it to use the same syntax where the 2 SDKs overlap.

• A client using only the admin SDK would interact through it's full interface
• A client accepting either SDK would interact through the common interface

As a programmer that uses both SDKs (even separately, as I assume most JS devs are), I find it really hard to argue that doing the same thing (operations supported by both SDKs) in arbitrarily different ways is valuable or desirable. And indeed, the SDKs today operate in almost identical ways, just with parallel type hierarchies. Locking the syntax into alignment creates a more consistent developer experience.

A path forwards??

This is how I imagine the change:

• Extract client-SDK types to a new package
• Update type usage in both SDKs to use common types
  • Where signatures diverge arbitrarily, fix inconsistencies
  • Where signatures diverge because one SDK provides meaningful additional functionality, subtype to add additional properties & methods or override method signatures (TypeScript has powerful method signature overrides)
• Where one SDK provides additional top-level features, subtype that product's root type & add methods (eg FirestoreAdmin which extends Firestore)
• Move both SDKs & the types to a monorepo ;p

Concrete examples

usability (e.g. method chaining)

Can you point me to an example? Isnt this a feature of most programming languages that's usable with both SDKs?? I'm mostly thinking about Firestore so perhaps I'm oblivious to some cool admin-SDK feature.

I do realize that I'm talking theory & optimistically. Maybe I can make a PoC.

[charles-allen]

Did you mean that method chaining propagates minor differences between types throughout the entire tree, such that all the types need to be overridden?

This might be the case. Thought TypeScript is very powerful, so there might be clever solutions to this.

But worst case:

• For most of the API you have 2 type hierarchies; same as now except they're aligned (one common + one admin override)
• Hopefully there are very few cases where the client SDK does something the admin SDK doesn't. In the spirit of substitutability, and to avoid a 3rd hierarchy, you might consider just adding all such client-only methods to the admin-SDK (potentially in addition to existing more powerful admin variants).

[hiranya911]

I'd like to add that the similarities between JS and Admin Node.js SDKs are limited to just RTDB and Firestore. Even in those cases there are minor but important differences. Our other product API surfaces (e.g. Auth, FCM, ML etc) are vastly different, and have nearly zero overlap across JS and Admin SDKs. Generally speaking, these 2 SDKs are meant for very different use cases, and therefore sharing typings across them is often infeasible.

I would argue that any divergence that causes contradiction is undesirable.

IMO it's the other way around. These 2 SDKs have mostly incompatible API surfaces, with Firestore and RTDB being the only exceptions where there's some degree of compatibility.

It's the product that defines the overall API, not the SDK.

It's actually the specific product use cases that define the APIs. Our SDKs are aimed at developers that implement very different (but often complementary) use cases. Taking Auth as an example, on frontends we want to support use cases like sign-in and sign-out. On backends we want to support use cases like creating custom tokens and assigning users roles.

It kind of makes sense why the JS and Admin API surfaces for RTDB and Firestore ended up being mostly similar. It's because they are database products. And as database products there's a set of use cases we'd want them to support regardless of the environment (queries, updates, transactions etc). But IMO this similarity is the exception rather than the norm.

[charles-allen]

the similarities between JS and Admin Node.js SDKs are limited to just RTDB and Firestore. Even in those cases there are minor but important differences.
...
this similarity is the exception rather than the norm.

Fair enough. I was coming from Firestore & made a rather unfounded extrapolation. I guess that's why we discuss ^^

I think I'll leave it here. For me personally having a common API even just for Firestore & Storage works really nicely for Web monorepos. I think it's still useful and possible to do at this scope, but I appreciate that it's less attractive if it's the exception not the rule.

Thanks to both of you for your feedback!

[akauppi]

Well, nothing prevents us from doing a reverse-compatibility layer on top of firebase-admin. :)