firestore-proto-codec 0.1.0

package/dist/index.js

@@ -0,0 +1,3 @@
+export { FirestoreProtoCodec, MAX_NESTING_DEPTH } from "./codec.js";
+export { CodecError } from "./errors.js";
+export { DefaultFirestoreTypes, FsBlob, FsGeoPoint, FsTimestamp, } from "./values.js";

package/dist/values.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ */
+export interface FirestoreTypes {
+    timestamp(seconds: bigint, nanos: number): unknown;
+    blob(bytes: Uint8Array): unknown;
+    geoPoint(latitude: number, longitude: number): unknown;
+    /** Return undefined when the value is not of this type, so decoding can
+     * report a useful error rather than throwing on a bad cast. */
+    readTimestamp(value: unknown): {
+        seconds: bigint;
+        nanos: number;
+    } | undefined;
+    readBlob(value: unknown): Uint8Array | undefined;
+    readGeoPoint(value: unknown): {
+        latitude: number;
+        longitude: number;
+    } | undefined;
+}
+export declare class FsTimestamp {
+    readonly seconds: bigint;
+    readonly nanos: number;
+    constructor(seconds: bigint, nanos: number);
+}
+export declare class FsBlob {
+    readonly bytes: Uint8Array;
+    constructor(bytes: Uint8Array);
+}
+export declare class FsGeoPoint {
+    readonly latitude: number;
+    readonly longitude: number;
+    constructor(latitude: number, longitude: number);
+}
+/** Dependency-free default. Swap in an SDK-specific implementation to write
+ * directly to Firestore. */
+export declare class DefaultFirestoreTypes 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;
+}

package/dist/values.js

@@ -0,0 +1,48 @@
+export class FsTimestamp {
+    seconds;
+    nanos;
+    constructor(seconds, nanos) {
+        this.seconds = seconds;
+        this.nanos = nanos;
+    }
+}
+export class FsBlob {
+    bytes;
+    constructor(bytes) {
+        this.bytes = bytes;
+    }
+}
+export class FsGeoPoint {
+    latitude;
+    longitude;
+    constructor(latitude, longitude) {
+        this.latitude = latitude;
+        this.longitude = longitude;
+    }
+}
+/** Dependency-free default. Swap in an SDK-specific implementation to write
+ * directly to Firestore. */
+export class DefaultFirestoreTypes {
+    timestamp(seconds, nanos) {
+        return new FsTimestamp(seconds, nanos);
+    }
+    blob(bytes) {
+        return new FsBlob(bytes);
+    }
+    geoPoint(latitude, longitude) {
+        return new FsGeoPoint(latitude, longitude);
+    }
+    readTimestamp(value) {
+        return value instanceof FsTimestamp
+            ? { seconds: value.seconds, nanos: value.nanos }
+            : undefined;
+    }
+    readBlob(value) {
+        return value instanceof FsBlob ? value.bytes : undefined;
+    }
+    readGeoPoint(value) {
+        return value instanceof FsGeoPoint
+            ? { latitude: value.latitude, longitude: value.longitude }
+            : undefined;
+    }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "firestore-proto-codec",
+  "version": "0.1.0",
+  "description": "Encode a protobuf message as a Firestore value, and decode it back.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/willbinge/firestore-proto-codec.git",
+    "directory": "ts"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./proto/*": "./proto/*"
+  },
+  "files": [
+    "dist",
+    "proto",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "generate": "./tool/generate.sh",
+    "test": "tsx --test test/*.test.ts",
+    "test:emulator": "npx --yes firebase-tools@15.27.0 emulators:exec --only firestore --project demo-codec 'tsx --test test/emulator.test.ts'",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@bufbuild/protobuf": "^2.2.0"
+  },
+  "devDependencies": {
+    "@bufbuild/protoc-gen-es": "^2.2.0",
+    "@google-cloud/firestore": "^9.0.1",
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}

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

@@ -0,0 +1,66 @@
+// Copyright 2026 Code Binge LLC
+
+syntax = "proto3";
+
+package codebinge.firestore.codec.v1;
+
+import "google/protobuf/descriptor.proto";
+
+option java_package = "com.codebinge.firestore.codec.v1";
+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.
+extend google.protobuf.FieldOptions {
+  Field field = 50000;
+}
+
+message Field {
+  // Never encoded.
+  bool skip = 1;
+
+  // Stored-name override. Exists only for adopting an existing collection;
+  // the default is the proto field name verbatim (§1).
+  string name = 2;
+
+  // Default: encode enum values as their name string (§4).
+  EnumEncoding enum_as = 3;
+
+  // Default true: omit singular scalar fields holding their default value (§6).
+  // Set false where an index or security rule depends on the field existing.
+  //
+  // Explicit presence is required. The intended default is true, and a proto3
+  // implicit-presence bool would not serialize `false`, leaving "set to false"
+  // indistinguishable from "not set".
+  optional bool omit_when_default = 4;
+
+  // Overrides the encoding inferred from the proto type.
+  Kind kind = 5;
+}
+
+enum Kind {
+  // Infer from the proto type. The default for every field.
+  KIND_UNSPECIFIED = 0;
+
+  // A project's own lat/lng message -> GeoPoint (§3.3). Not needed for
+  // google.type.LatLng, which is recognized automatically. The annotated
+  // message must have exactly two double fields named `latitude` and
+  // `longitude`.
+  KIND_GEO_POINT = 1;
+
+  // uint64/fixed64 -> Integer rather than String, keeping the field ordered
+  // and queryable. Throws at encode time above 2^63-1 (§2.1).
+  KIND_UNSIGNED_AS_INTEGER = 2;
+}
+
+enum EnumEncoding {
+  ENUM_ENCODING_NAME = 0;
+  ENUM_ENCODING_NUMBER = 1;
+}