feat(firestore): add VectorValue type and vector() API

[Pelleking]

feat(firestore): add VectorValue type and vector() API

Adds Firestore Vector field support to React Native Firebase:

• New VectorValue class and vector(values?: number[]) constructor
• End-to-end JS ↔ native serialization/deserialization (iOS/Android) and web-fallback
• Modular and namespaced surfaces (edit by @mikehardy - not adding new namespaced API surface area)

Motivation

Brings RNFB Firestore to parity with Firebase SDKs that added Vector support:

• JS SDK APIs (10.13): PR reference

• iOS (11.10.0): release notes

• Android (25.1.0): release notes

• Fixes 🐛 [Firestore] Vector Type Support #8442

API

• Modular:
  • import { VectorValue, vector } from '@react-native-firebase/firestore'
  • Example: await setDoc(docRef, { embedding: vector([0.1, 0.2, 0.3]) })
• Namespaced:
  • firebase.firestore.VectorValue, firebase.firestore.vector(values)

Implementation

• JS runtime: VectorValue with validation, isEqual, toJSON, static fromJSON, toArray
• Type map: added vector type; wired into generateNativeData and parseNativeData
• Web fallback: maps to JS SDK VectorValue in web/convert.js
• Typings: VectorValue type and vector() declaration; added to DocumentFieldType
• Tests: unit test covers construction and serializer round-trip

Minimum native versions for full functionality:

• iOS Firestore ≥ 11.10.0
• Android Firestore ≥ 25.1.0
  Older SDKs won’t crash (reflection guards), but vectors will not function. (edit by @mikehardy - min SDKs already present since prior to last RNFB breaking change, no problem)

Usage Example

import firestore, { vector } from '@react-native-firebase/firestore';

await firestore()
  .doc(`users/${userId}/todo/${page.id}/items/${id}`)
  .set({
    text: todoText,
    done: false,
    createdAt: now,
    embedding: vector([0.12, 0.34, 0.56]),
  });

const snap = await firestore().doc(`users/${userId}/todo/${page.id}/items/${id}`).get();
const v = snap.get('embedding'); // VectorValue
console.log('read vector:', v.toArray());

Tests

• Jest unit: packages/firestore/__tests__/vector.test.ts
• Validates construction, equality, serializer round-trip (JS ↔ native type map)

Types

• Updated packages/firestore/lib/index.d.ts to include VectorValue, vector(), and DocumentFieldType union

Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.

  • Yes

• My change supports the following platforms;

  • Android
  • iOS
  • Other (web)

• My change includes tests;

  • e2e tests added or updated in packages/**/e2e
  • jest tests added or updated in packages/**/__tests__

• I have updated TypeScript types that are affected by my change.

• This is a breaking change;

  • Yes
  • No

Notes

• Bridges use reflection to avoid hard dependency on newer native symbols at build time.
• If project native SDKs are older than the minimums above, vector fields won’t be usable (graceful no-op).

[vercel]

@Pelleking is attempting to deploy a commit to the Invertase Team on Vercel.

A member of the Team first needs to authorize it.

[CLAassistant]

All committers have signed the CLA.

[Pelleking]

The issue it resolves #8442

[mikehardy]

Hey @Pelleking 👋 ! Sorry this has sat, it's through no fault of your own, I've got quite a stack of PRs to review right now in this repo and this is definitely one of them.

One thing I can do is approve the workflows though - in particular, you might like the output of the "patches" workflow that generates a set of patches compatible with patch-package, so you may continue to rely on the public packages we publish on npmjs.org, but apply the changes you need on top of them until this is merged

[Pelleking]

@mikehardy Could you please rerun the workflows?

[mikehardy]

Reviewer note - need to pull this along with withConverter PR support to check intersectionality - both of these are going to land, then after we can stage firestore for typescript-native conversion

• feat(firestore): implement withCoverter #8744

Re-running CI now and there have been a few CI fixes recently that may need to be rebased in here - in particular an android emulator hang when v36 of the emu came out a few days ago resolved with a version pin

[mikehardy]

some quick comments - all seem pretty easy, I'll try to push the suggested changes and get this merged quickly as we've got a lot of Firestore work queued up and it is all inter-related / will conflict

• vector -> Vector.fromJSON static to match firebase-js-sdk types
  • Vector.fromJSON still needs an implementation, but in fact vector is a correct JS API
    
• native code should rely on concrete types vs reflection, analysis shows it is non-breaking
• some I-think-unnecessary conditional definition checks are likely not needed
• looks like native code mostly treats VectorValue as a FieldValue
  • tests should be nested into the FieldValue e2e area
    • tests are currently attempting to operate on a doc ref that doesn't have permission
  • FieldValue parsing should be used I think in the serializer - not a new main type but a new FieldValue sub-type

[mikehardy]

I have local e2e passing now after a bit of test alteration and some code change on native side
Just a little nudge on the JS typing and it's good to go

This one was admittedly confusing for me - I haven't used the vector feature before and the typing is such that it is sort of a FieldValue (which threw me off) but is in the end not quite a FieldValue (because it isn't just a sentinel, they come back in document fetch as well). A strange-ish hybrid type.

Anyway, serialization is working well now with just minor tweaks to make it reflexive vs concrete - just need to true up the JS API to match firebase-js-sdk

[mikehardy]

• matches firebase-js-sdk modular API surface area and documentation now
• added types test entries
• passing all unit and e2e tests locally

should be good to go

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
react-native-firebase	Ready	Preview, Comment	Dec 31, 2025 6:16pm

[Pelleking]

Thank you so much @mikehardy for the help!

[mikehardy]

Happy to help @Pelleking thanks for the original contribution and the patience