firestore-proto-codec 0.1.0 → 0.3.0

package/README.md

@@ -45,34 +45,35 @@ int64; decoding hands them back as strings.
 ## Binding to an SDK
 
 The default adapter emits dependency-free `FsTimestamp` / `FsBlob` /
-`FsGeoPoint`. Supply your own to write straight to Firestore:
+`FsGeoPoint`, which the admin SDK refuses outright: it rejects custom
+prototypes, so a forgotten adapter throws at the write and stores nothing.
+
+For `firebase-admin` / `@google-cloud/firestore`, the adapter ships:
 
 ```ts
-class AdminTypes implements FirestoreTypes {
-  timestamp = (seconds: bigint, nanos: number) =>
-    new Timestamp(Number(seconds), nanos);
-  blob = (bytes: Uint8Array) => Buffer.from(bytes);
-  geoPoint = (lat: number, lng: number) => new GeoPoint(lat, lng);
-
-  readTimestamp = (v: unknown) =>
-    v instanceof Timestamp
-      ? { seconds: BigInt(v.seconds), nanos: v.nanoseconds }
-      : undefined;
-  // Buffer extends Uint8Array, so this covers both.
-  readBlob = (v: unknown) =>
-    v instanceof Uint8Array ? new Uint8Array(v) : undefined;
-  readGeoPoint = (v: unknown) =>
-    v instanceof GeoPoint
-      ? { latitude: v.latitude, longitude: v.longitude }
-      : undefined;
-}
-
-const codec = new FirestoreProtoCodec(new AdminTypes());
+import { adminCodec } from "firestore-proto-codec/admin";
+
+await doc.set(adminCodec.encode(TaskSchema, task));
 ```
 
-Verified against `@google-cloud/firestore` 9.0.1: there is no `Bytes` class in
-the admin SDK (that one belongs to the web client SDK), and bytes values are
-plain `Buffer`s.
+`AdminFirestoreTypes` comes from the same subpath if you would rather construct
+the codec yourself. `@google-cloud/firestore` is an **optional peer
+dependency** — only that subpath imports it, so the root entry point still
+carries no Firebase dependency. `firebase-admin` already depends on it, so a
+hoisted layout resolves it with nothing added; a strict one (pnpm, Yarn PnP)
+needs `@google-cloud/firestore` in your own dependencies.
+
+Its reads are structural rather than `instanceof`. The codec only calls them at
+a position the schema has already declared a `Timestamp`, `bytes` or `LatLng`,
+so there is no type to discriminate and nothing to lose — and a structural
+check survives two copies of `@google-cloud/firestore` in the tree, which would
+otherwise make `instanceof` false and fail every read with
+`expected a timestamp`.
+
+For any other SDK, implement `FirestoreTypes` yourself; [src/admin.ts](src/admin.ts)
+is the worked example. Verified against `@google-cloud/firestore` 9.0.1: there
+is no `Bytes` class in the admin SDK (that one belongs to the web client SDK),
+and bytes values are plain `Buffer`s.
 
 Keeping this an interface is why the core has no Firebase dependency.
 
@@ -164,8 +165,9 @@ It needs a JDK 21 or newer, which the Firestore emulator requires;
 `firebase-tools` is fetched by the script at a pinned version, so the emulator
 build is the same one CI runs. The suite is skipped when
 `FIRESTORE_EMULATOR_HOST` is unset, so `npm test` stays green without a JDK.
-`@google-cloud/firestore` is a dev dependency only -- the published package
-still has no Firebase dependency.
+`@google-cloud/firestore` is a dev dependency and an optional peer -- nothing
+but the `/admin` subpath imports it, so the root entry point has no Firebase
+dependency.
 
 Nothing in a pull request can change what the server does, so CI runs this
 [weekly](../.github/workflows/emulator.yml) rather than per-PR, and it can be

package/dist/admin.d.ts

@@ -0,0 +1,28 @@
+import { FirestoreProtoCodec } from "./codec.js";
+import type { FirestoreTypes } from "./values.js";
+/**
+ * The reads are structural rather than `instanceof`. They can afford to be:
+ * the codec never uses them to discriminate a type, only to unwrap a value at
+ * a position the schema has already declared a `Timestamp`, `bytes` or
+ * `LatLng`, so a loose check cannot misclassify anything. What it buys is
+ * immunity to two copies of `@google-cloud/firestore` in the tree -- a
+ * version-range accident a consumer does not control, which makes `instanceof`
+ * false and turns every read into `expected a timestamp`. That failure reads
+ * like data corruption rather than like a dependency problem.
+ */
+export declare class AdminFirestoreTypes implements FirestoreTypes {
+    timestamp(seconds: bigint, nanos: number): unknown;
+    blob(bytes: Uint8Array): unknown;
+    geoPoint(latitude: number, longitude: number): unknown;
+    readTimestamp(value: unknown): {
+        seconds: bigint;
+        nanos: number;
+    } | undefined;
+    readBlob(value: unknown): Uint8Array | undefined;
+    readGeoPoint(value: unknown): {
+        latitude: number;
+        longitude: number;
+    } | undefined;
+}
+/** Shared instance: the codec keeps no per-call state. */
+export declare const adminCodec: FirestoreProtoCodec;

package/dist/admin.js

@@ -0,0 +1,70 @@
+/**
+ * `FirestoreTypes` for the Firestore Admin SDK. `firebase-admin/firestore` and
+ * `@google-cloud/firestore` re-export the same `Timestamp` and `GeoPoint`, so
+ * this adapter serves both.
+ *
+ * ```ts
+ * import { adminCodec } from "firestore-proto-codec/admin";
+ * ```
+ *
+ * Not a convenience: without an adapter the codec emits `FsTimestamp` /
+ * `FsBlob` / `FsGeoPoint`, and the admin SDK refuses a custom prototype
+ * outright, so the write throws and stores nothing (pinned by
+ * test/emulator.test.ts). Every admin consumer needs this, which is why it
+ * ships here rather than being copied out of the README.
+ *
+ * `@google-cloud/firestore` is an optional peer dependency. Only this module
+ * imports it -- the root entry point stays dependency-free.
+ */
+import { GeoPoint, Timestamp } from "@google-cloud/firestore";
+import { FirestoreProtoCodec } from "./codec.js";
+/**
+ * The reads are structural rather than `instanceof`. They can afford to be:
+ * the codec never uses them to discriminate a type, only to unwrap a value at
+ * a position the schema has already declared a `Timestamp`, `bytes` or
+ * `LatLng`, so a loose check cannot misclassify anything. What it buys is
+ * immunity to two copies of `@google-cloud/firestore` in the tree -- a
+ * version-range accident a consumer does not control, which makes `instanceof`
+ * false and turns every read into `expected a timestamp`. That failure reads
+ * like data corruption rather than like a dependency problem.
+ */
+export class AdminFirestoreTypes {
+    timestamp(seconds, nanos) {
+        // Firestore spans years 1--9999, so seconds stays far inside
+        // Number.MAX_SAFE_INTEGER and the narrowing is lossless.
+        return new Timestamp(Number(seconds), nanos);
+    }
+    blob(bytes) {
+        // Copies rather than viewing `bytes.buffer`: a pending write must not
+        // change under a caller who mutates the message after encoding it.
+        return Buffer.from(bytes);
+    }
+    geoPoint(latitude, longitude) {
+        return new GeoPoint(latitude, longitude);
+    }
+    readTimestamp(value) {
+        const ts = value;
+        return typeof ts?.seconds === "number" &&
+            typeof ts?.nanoseconds === "number" &&
+            typeof ts?.toDate === "function"
+            ? { seconds: BigInt(ts.seconds), nanos: ts.nanoseconds }
+            : undefined;
+    }
+    readBlob(value) {
+        // `instanceof` is right here, unlike above: `Uint8Array` is a realm
+        // intrinsic, not a package export, so a duplicated dependency cannot
+        // detach it. The copy hands the decoded message a plain `Uint8Array`
+        // rather than the SDK's `Buffer`, which a strict deep-equal against an
+        // encoded message would otherwise report as a type mismatch.
+        return value instanceof Uint8Array ? new Uint8Array(value) : undefined;
+    }
+    readGeoPoint(value) {
+        const point = value;
+        return typeof point?.latitude === "number" &&
+            typeof point?.longitude === "number"
+            ? { latitude: point.latitude, longitude: point.longitude }
+            : undefined;
+    }
+}
+/** Shared instance: the codec keeps no per-call state. */
+export const adminCodec = new FirestoreProtoCodec(new AdminFirestoreTypes());

package/dist/generated/codebinge/firestore/codec/v1/options_pb.d.ts

@@ -100,6 +100,6 @@ export declare enum EnumEncoding {
  */
 export declare const EnumEncodingSchema: GenEnum<EnumEncoding>;
 /**
- * @generated from extension: codebinge.firestore.codec.v1.Field field = 50000;
+ * @generated from extension: codebinge.firestore.codec.v1.Field field = 1376;
  */
 export declare const field: GenExtension<FieldOptions, Field>;

package/dist/generated/codebinge/firestore/codec/v1/options_pb.js

@@ -4,7 +4,7 @@ import { file_google_protobuf_descriptor } from "@bufbuild/protobuf/wkt";
 /**
  * Describes the file codebinge/firestore/codec/v1/options.proto.
  */
-export const file_codebinge_firestore_codec_v1_options = /*@__PURE__*/ fileDesc("Cipjb2RlYmluZ2UvZmlyZXN0b3JlL2NvZGVjL3YxL29wdGlvbnMucHJvdG8SHGNvZGViaW5nZS5maXJlc3RvcmUuY29kZWMudjEiyAEKBUZpZWxkEgwKBHNraXAYASABKAgSDAoEbmFtZRgCIAEoCRI7CgdlbnVtX2FzGAMgASgOMiouY29kZWJpbmdlLmZpcmVzdG9yZS5jb2RlYy52MS5FbnVtRW5jb2RpbmcSHgoRb21pdF93aGVuX2RlZmF1bHQYBCABKAhIAIgBARIwCgRraW5kGAUgASgOMiIuY29kZWJpbmdlLmZpcmVzdG9yZS5jb2RlYy52MS5LaW5kQhQKEl9vbWl0X3doZW5fZGVmYXVsdCpOCgRLaW5kEhQKEEtJTkRfVU5TUEVDSUZJRUQQABISCg5LSU5EX0dFT19QT0lOVBABEhwKGEtJTkRfVU5TSUdORURfQVNfSU5URUdFUhACKkAKDEVudW1FbmNvZGluZxIWChJFTlVNX0VOQ09ESU5HX05BTUUQABIYChRFTlVNX0VOQ09ESU5HX05VTUJFUhABOloKBWZpZWxkEh0uZ29vZ2xlLnByb3RvYnVmLkZpZWxkT3B0aW9ucxjQhgMgASgLMiMuY29kZWJpbmdlLmZpcmVzdG9yZS5jb2RlYy52MS5GaWVsZFIFZmllbGRCJAogY29tLmNvZGViaW5nZS5maXJlc3RvcmUuY29kZWMudjFQAWIGcHJvdG8z", [file_google_protobuf_descriptor]);
+export const file_codebinge_firestore_codec_v1_options = /*@__PURE__*/ fileDesc("Cipjb2RlYmluZ2UvZmlyZXN0b3JlL2NvZGVjL3YxL29wdGlvbnMucHJvdG8SHGNvZGViaW5nZS5maXJlc3RvcmUuY29kZWMudjEiyAEKBUZpZWxkEgwKBHNraXAYASABKAgSDAoEbmFtZRgCIAEoCRI7CgdlbnVtX2FzGAMgASgOMiouY29kZWJpbmdlLmZpcmVzdG9yZS5jb2RlYy52MS5FbnVtRW5jb2RpbmcSHgoRb21pdF93aGVuX2RlZmF1bHQYBCABKAhIAIgBARIwCgRraW5kGAUgASgOMiIuY29kZWJpbmdlLmZpcmVzdG9yZS5jb2RlYy52MS5LaW5kQhQKEl9vbWl0X3doZW5fZGVmYXVsdCpOCgRLaW5kEhQKEEtJTkRfVU5TUEVDSUZJRUQQABISCg5LSU5EX0dFT19QT0lOVBABEhwKGEtJTkRfVU5TSUdORURfQVNfSU5URUdFUhACKkAKDEVudW1FbmNvZGluZxIWChJFTlVNX0VOQ09ESU5HX05BTUUQABIYChRFTlVNX0VOQ09ESU5HX05VTUJFUhABOlkKBWZpZWxkEh0uZ29vZ2xlLnByb3RvYnVmLkZpZWxkT3B0aW9ucxjgCiABKAsyIy5jb2RlYmluZ2UuZmlyZXN0b3JlLmNvZGVjLnYxLkZpZWxkUgVmaWVsZEIkCiBjb20uY29kZWJpbmdlLmZpcmVzdG9yZS5jb2RlYy52MVABYgZwcm90bzM", [file_google_protobuf_descriptor]);
 /**
  * Describes the message codebinge.firestore.codec.v1.Field.
  * Use `create(FieldSchema)` to create a new message.
@@ -61,6 +61,6 @@ export var EnumEncoding;
  */
 export const EnumEncodingSchema = /*@__PURE__*/ enumDesc(file_codebinge_firestore_codec_v1_options, 1);
 /**
- * @generated from extension: codebinge.firestore.codec.v1.Field field = 50000;
+ * @generated from extension: codebinge.firestore.codec.v1.Field field = 1376;
  */
 export const field = /*@__PURE__*/ extDesc(file_codebinge_firestore_codec_v1_options, 0);

package/dist/values.d.ts

@@ -1,8 +1,13 @@
 /**
  * Firestore has three value types protobuf cannot express as plain data.
  * Implement this to bind them to a particular SDK's classes -- `Timestamp`,
- * `Bytes`, and `GeoPoint` in `firebase-admin`, for example. Everything else in
- * the encoding is a plain string, number, bigint, boolean, array, or object.
+ * `Buffer`, and `GeoPoint` in `firebase-admin`, for example. (Bytes are plain
+ * `Buffer`s there; the `Bytes` class belongs to the web client SDK.)
+ * Everything else in the encoding is a plain string, number, bigint, boolean,
+ * array, or object.
+ *
+ * The admin implementation ships as `firestore-proto-codec/admin`. Write your
+ * own only for another SDK.
  */
 export interface FirestoreTypes {
     timestamp(seconds: bigint, nanos: number): unknown;
@@ -34,8 +39,9 @@ export declare class FsGeoPoint {
     readonly longitude: number;
     constructor(latitude: number, longitude: number);
 }
-/** Dependency-free default. Swap in an SDK-specific implementation to write
- * directly to Firestore. */
+/** Dependency-free default. It cannot write to Firestore: the admin SDK
+ * refuses these custom prototypes outright. Swap in an SDK-specific
+ * implementation -- `firestore-proto-codec/admin` for firebase-admin. */
 export declare class DefaultFirestoreTypes implements FirestoreTypes {
     timestamp(seconds: bigint, nanos: number): unknown;
     blob(bytes: Uint8Array): unknown;

package/dist/values.js

@@ -20,8 +20,9 @@ export class FsGeoPoint {
         this.longitude = longitude;
     }
 }
-/** Dependency-free default. Swap in an SDK-specific implementation to write
- * directly to Firestore. */
+/** Dependency-free default. It cannot write to Firestore: the admin SDK
+ * refuses these custom prototypes outright. Swap in an SDK-specific
+ * implementation -- `firestore-proto-codec/admin` for firebase-admin. */
 export class DefaultFirestoreTypes {
     timestamp(seconds, nanos) {
         return new FsTimestamp(seconds, nanos);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firestore-proto-codec",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Encode a protobuf message as a Firestore value, and decode it back.",
   "license": "Apache-2.0",
   "repository": {
@@ -16,6 +16,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./admin": {
+      "types": "./dist/admin.d.ts",
+      "default": "./dist/admin.js"
+    },
     "./proto/*": "./proto/*"
   },
   "files": [
@@ -34,6 +38,14 @@
   "dependencies": {
     "@bufbuild/protobuf": "^2.2.0"
   },
+  "peerDependencies": {
+    "@google-cloud/firestore": ">=6"
+  },
+  "peerDependenciesMeta": {
+    "@google-cloud/firestore": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@bufbuild/protoc-gen-es": "^2.2.0",
     "@google-cloud/firestore": "^9.0.1",

package/proto/codebinge/firestore/codec/v1/options.proto

@@ -11,15 +11,17 @@ option java_multiple_files = true;
 
 // Per-field encoding options. See docs/encoding.md §7.
 //
-// NOTE: extension number 50000 is provisional. 50000-99999 is protobuf's
-// organization-internal range -- shared scratch space every organization is told
-// to use freely -- so a collision there is documented behavior, not bad luck,
-// and it surfaces as soon as two published schemas meet in one descriptor pool.
-// protocolbuffers/protobuf#29013 reports exactly that failure. Replace this with
-// a Global Extension Registry number before any public release: changing it
-// afterwards is breaking, and it is baked into generated identifiers too.
+// Extension number 1376 is registered to this project in protobuf's Global
+// Extension Registry, which reserves 1376-1380 for it. Do not change it: the
+// number is baked into every generated artifact and into every consumer .proto,
+// and a consumer still on an old number stops seeing the annotation silently
+// rather than failing.
+//
+// The remaining four are held for future extend sites. Each extend site
+// consumes one number, so extending MessageOptions (or any other descriptor
+// options message) takes the next one, 1377 -- not a reuse of this one.
 extend google.protobuf.FieldOptions {
-  Field field = 50000;
+  Field field = 1376;
 }
 
 message Field {