feat(firestore): decouple handwritten sdk wrapper from embedded gapic clients by quirogas · Pull Request #8928 · googleapis/google-cloud-node

quirogas · 2026-07-21T22:28:45Z

Decouple the handwritten Firestore SDK wrapper from embedded GAPIC client implementations by transitioning to the standalone @google-cloud/firestore-api package. Standalone -api packages are now generated and versioned independently.

Summary of Changes

GAPIC Dependency: Adds runtime dependency on standalone @google-cloud/firestore-api (^0.2.0).
Runtime Proto Delegation: Replaces static compiled protobuf runtime files in dev/protos/*.js (firestore_v1, firestore_admin_v1, firestore_v1beta1) with dynamic forwarding exports directly to @google-cloud/firestore-api/build/protos/protos, removing 76,572 lines of static JavaScript.
Getter Variable Caching: Applies local variable caching around lazy getters in dev/src/index.ts to ensure referential equality (===) and avoid redundant module require and Object.assign execution on repeated accesses.
Deprecation Guidance: Adds explicit JSDoc @deprecated annotations directing consumers to import @google-cloud/firestore-api directly instead of relying on re-exported client properties (Firestore.v1).
Build Script Cleanup: Removes legacy OwlBot configuration (owlbot.py, .OwlBot.yaml) and proto compilation scripts (dev/protos/update.sh).

Why Local Types Remain in This Commit

Historically, dev/protos/update.sh compiled static protobuf TypeScript interfaces (firestore_v1_proto_api.d.ts) using custom post-processing: passing --force-enum-string to force protobuf enums into string literal unions ('ASCENDING' | 'DESCENDING'), and executing a Perl regex to replace 64-bit integer Long references with string. Modern GAPIC packages generate standard numeric enums and number | Long.

In this initial pull request, we intentionally retain firestore_v1_proto_api.d.ts while delegating .js runtime files to @google-cloud/firestore-api. This is done specifically in PR #1 to separate the mechanical work of separating the library dependency from the deeper call-site refactoring required to transition from string literals to native GAPIC enums. Once the entire stacked series merges, the final state will be complete reliance on @google-cloud/firestore-api as our single source of truth for all types and runtime models.

Internal: b/531788771

📚 Stack Navigation Index

Layer 1 (Base Disentanglement & Runtime Forwarding): feat(firestore): decouple handwritten sdk wrapper from embedded gapic clients #8928
Layer 2 (Complete Decoupling & Dead Code Cleanup): feat(firestore)!: complete gapic decoupling, adopt subpath imports, and remove legacy proto code (#9074) #9074
Layer 3 (Automated Presubmit Bundle Size Guard): chore(firestore): add automated presubmit serverless bundle size regression guard (#9075) #9075
Layer 4 (Call-Site Modernization & Eliminate Local Protos): refactor(firestore): modernize internal proto call sites and eliminate local declarations (#9076) #9076

gemini-code-assist

Code Review

This pull request removes auto-generated configuration and proto files, transitioning the Firestore library to depend on the external @google-cloud/firestore-api package. Imports and lazy-loading getters for v1 and v1beta1 are updated accordingly. The review feedback highlights opportunities to optimize performance and code cleanliness: first, by directly requiring @google-cloud/firestore-api in the client factory to avoid repeatedly triggering lazy getters; and second, by caching the loaded modules in the lazy getters for v1 and v1beta1 to prevent redundant module loading and property copying on multiple accesses.

…GrpcStatus JSDoc

…store-handwritten

quirogas · 2026-07-27T18:51:45Z

-
-logging.basicConfig(level=logging.DEBUG)
-
-staging = Path("owl-bot-staging")


We no longer need to copy the gapic files into dev, as they are now live in their own separate library: https://www.npmjs.com/package/@google-cloud/firestore-api.

…g JSDoc deprecation guidance

…rarian keep list (googleapis#8928)

googleapis#8928)

…rarian keep list (googleapis#8928)

googleapis#8928)

…eslintrc (googleapis#8928) - Update typescript import namespace in bin/linter.mjs (Option 2) to fix ts.sys undefined error - Execute ESLint and tsc via child process inside target package directory using package local compilers when available - Update handwritten/firestore/.eslintrc.json to extend root gts config instead of local node_modules

googleapis#8928)

…apis#8928)

… origin/main (googleapis#8928)

…obuf reflection serialization (googleapis#8928)

…gleapis#8928)

…ntax fix (googleapis#8928)

…estore-api (googleapis#8928)

…googleapis#8928)

… delegating google protos (googleapis#8928)

… callsite modernization (googleapis#8928)

…v1beta1 generation (googleapis#8928)

…erated protos.js (googleapis#8928)

…e local declarations (googleapis#8928) - Remove dev/protos/firestore_v1_proto_api.* and dev/protos/v1.json to transition @google-cloud/firestore-api into our automated Single Source of Truth for TypeScript declarations - Extract custom offline bundle persistence interface definitions into standalone dev/src/bundle-proto.* modules - Update query operator dictionaries (directionOperators, comparisonOperators) and internal comparators to consume native GAPIC enum objects and 64-bit Long structures - Verify 100% clean compilation and passing unit test suites across watch, partition-query, aggregate-query, and transaction operations

…onfiguration file mappings (googleapis#8928) - Remove wildcard asterisk export entries (./v1/*, ./protos/*, ./build/*) to prevent external reliance on private implementation scripts - Add explicit named subpath export mappings for firestore_client_config.json and protos.json to ensure zero breaking changes across internal wrapper consumers - Verify 100% passing test execution across all client and admin service operations

…cy, and discontinue v1beta1 (#9073) Parallel architectural update to `@google-cloud/firestore-api` supporting the handwritten Firestore SDK disentanglement (#8928). ### Summary of Changes - **Runtime `long` Dependency**: Moves `"long"` from `devDependencies` to runtime `"dependencies"`. Generated declaration files (`protos.d.ts`) explicitly import `long`. In environments using strict package managers with node_modules isolation (such as `pnpm`), omitting `long` from runtime dependencies causes TypeScript compilation to fail with `error TS2307: Cannot find module 'long'` (per structural context in `googleapis/nodejs-firestore#2322`). - **Subpath Exports**: Configures conditional subpath exports (`./v1`, `./client_v1`, `./admin_v1`, `./protos`, and configuration files) with the `"types"` condition placed before `"default"`. This ensures declaration files resolve correctly for consumers using modern TypeScript module resolution (`"moduleResolution": "nodenext"`). - **Discontinue `v1beta1`**: Removed `v1beta1` from `librarian.yaml` and regenerated the library via `librarian` to stop generating beta client code. Internal: b/531788771

MarkDuckworth

Looks good in context of the stacked PRs

quirogas · 2026-08-06T17:27:20Z

Labeling as "do not merge" to make sure we merge all stacked prs before merging this one.

quirogas added 3 commits July 21, 2026 10:14

feat(firestore): use @google-cloud/firestore-api dependency

ae7feb8

feat(firestore): re-export protos and support legacy v1 constructor

772df4e

Merge branch 'main' into feat/disentangle-firestore-handwritten

541c5ba

quirogas self-assigned this Jul 21, 2026

product-auto-label Bot added the api: firestore Issues related to the Firestore API. label Jul 21, 2026

gemini-code-assist Bot reviewed Jul 21, 2026

View reviewed changes

Comment thread handwritten/firestore/dev/src/index.ts

Comment thread handwritten/firestore/dev/src/index.ts

Comment thread handwritten/firestore/dev/src/index.ts

quirogas marked this pull request as ready for review July 23, 2026 18:05

quirogas requested a review from a team as a code owner July 23, 2026 18:05

MarkDuckworth reviewed Jul 23, 2026

View reviewed changes

quirogas added 2 commits July 27, 2026 14:54

refactor(firestore): add v1/v1beta1 deprecation warnings and restore …

9537858

…GrpcStatus JSDoc

Merge remote-tracking branch 'origin/main' into feat/disentangle-fire…

f6e3bf7

…store-handwritten

quirogas commented Jul 27, 2026

View reviewed changes

quirogas requested a review from MarkDuckworth July 28, 2026 22:36

Merge branch 'main' into feat/disentangle-firestore-handwritten

7ac1421

quirogas enabled auto-merge (squash) July 29, 2026 23:03

MarkDuckworth reviewed Jul 30, 2026

View reviewed changes

Comment thread handwritten/firestore/dev/src/index.ts Outdated

Comment thread handwritten/firestore/types/firestore.d.ts Outdated

Comment thread handwritten/firestore/owlbot.py

Comment thread handwritten/firestore/owlbot.py

fix(firestore): address PR googleapis#8928 review comments by updatin…

98b728c

…g JSDoc deprecation guidance

quirogas added a commit to quirogas/google-cloud-node that referenced this pull request Aug 3, 2026

feat(firestore-api): implement modular subpath exports and update lib…

7dfbb01

…rarian keep list (googleapis#8928)

Merge branch 'main' into feat/disentangle-firestore-handwritten

faf5a3d

quirogas added a commit to quirogas/google-cloud-node that referenced this pull request Aug 3, 2026

chore(firestore): add automated presubmit bundle size regression check (

862d6dd

googleapis#8928)

quirogas added a commit to quirogas/google-cloud-node that referenced this pull request Aug 3, 2026

feat(firestore-api): implement modular subpath exports and update lib…

ac624dd

…rarian keep list (googleapis#8928)

quirogas added a commit to quirogas/google-cloud-node that referenced this pull request Aug 3, 2026

feat(firestore-api): implement modular subpath exports and update lib…

526b75e

…rarian keep list (googleapis#8928)

quirogas added a commit to quirogas/google-cloud-node that referenced this pull request Aug 4, 2026

chore(firestore): add automated presubmit bundle size regression check (

209ac39

googleapis#8928)

quirogas requested a review from a team as a code owner August 4, 2026 00:05

quirogas added a commit to quirogas/google-cloud-node that referenced this pull request Aug 4, 2026

chore(firestore): add automated presubmit bundle size regression check (

1e330bf

googleapis#8928)

quirogas force-pushed the feat/disentangle-firestore-handwritten branch from a1fc42e to f995b89 Compare August 4, 2026 00:05

quirogas added a commit to quirogas/google-cloud-node that referenced this pull request Aug 4, 2026

chore(firestore): add automated presubmit bundle size regression check (

295baff

googleapis#8928)

quirogas force-pushed the feat/disentangle-firestore-handwritten branch from f995b89 to a833777 Compare August 4, 2026 00:24

revert(ci): restore upstream workflow files and linter script (google…

8fe51a9

…apis#8928)

quirogas added a commit to quirogas/google-cloud-node that referenced this pull request Aug 4, 2026

revert(ci): restore upstream workflow files and linter script (google…

ade8752

…apis#8928)

quirogas added a commit to quirogas/google-cloud-node that referenced this pull request Aug 4, 2026

revert(ci): restore upstream workflow files and linter script (google…

f2cfb91

…apis#8928)

revert(ci): align workflow files and linter script with true upstream…

9b56b8f

… origin/main (googleapis#8928)

quirogas added a commit to quirogas/google-cloud-node that referenced this pull request Aug 4, 2026

revert(ci): align workflow files and linter script with true upstream…

8cad739

… origin/main (googleapis#8928)

quirogas added a commit to quirogas/google-cloud-node that referenced this pull request Aug 4, 2026

revert(ci): align workflow files and linter script with true upstream…

e072c0d

… origin/main (googleapis#8928)

quirogas added a commit to quirogas/google-cloud-node that referenced this pull request Aug 4, 2026

fix(firestore-api): move long to runtime dependencies to resolve prot…

9e11c3d

…obuf reflection serialization (googleapis#8928)

feat(firestore): cache evaluated lazy getters for v1 and v1beta1 (goo…

0852d92

…gleapis#8928)

quirogas added a commit to quirogas/google-cloud-node that referenced this pull request Aug 4, 2026

refactor(firestore): delete obsolete cloned google proto files and sy…

fa5b568

…ntax fix (googleapis#8928)

quirogas added 3 commits August 4, 2026 00:21

refactor(firestore): delegate runtime protobuf models directly to fir…

26e14ae

…estore-api (googleapis#8928)

fix(firestore): add valid license headers to forwarded proto js files (…

f94c08f

…googleapis#8928)

fix(firestore): preserve runtime bundle serialization namespace while…

3c812d3

… delegating google protos (googleapis#8928)

quirogas added a commit to quirogas/google-cloud-node that referenced this pull request Aug 4, 2026

refactor(firestore): extract bundle serialization interface and begin…

e781fa2

… callsite modernization (googleapis#8928)

quirogas disabled auto-merge August 4, 2026 08:06

quirogas changed the title ~~feat(firestore): split GAPIC from the firestore handwritten package~~ feat(firestore): decouple handwritten sdk wrapper from embedded gapic clients Aug 4, 2026

quirogas added a commit to quirogas/google-cloud-node that referenced this pull request Aug 4, 2026

feat(firestore-api): adopt conditional subpath type exports and stop …

1741c8e

…v1beta1 generation (googleapis#8928)

quirogas added a commit to quirogas/google-cloud-node that referenced this pull request Aug 4, 2026

chore(firestore-api): apply gapic-node-processing minification to gen…

c7672f3

…erated protos.js (googleapis#8928)

quirogas mentioned this pull request Aug 4, 2026

feat(firestore-api): implement subpath exports, declare long dependency, and discontinue v1beta1 #9073

Merged

quirogas requested a review from MarkDuckworth August 5, 2026 01:24

MarkDuckworth approved these changes Aug 5, 2026

View reviewed changes

quirogas added the do not merge Indicates a pull request not ready for merge, due to either quality or timing. label Aug 6, 2026


		logging.basicConfig(level=logging.DEBUG)

		staging = Path("owl-bot-staging")

Uh oh!

Conversation

quirogas commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of Changes

Why Local Types Remain in This Commit

📚 Stack Navigation Index

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

quirogas Jul 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MarkDuckworth left a comment

Choose a reason for hiding this comment

Uh oh!

quirogas commented Aug 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

quirogas commented Jul 21, 2026 •

edited

Loading