@dalgo/firestore 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Strongo Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+# DALgo adapter for Firestore Web
+
+`@dalgo/firestore` implements the
+[`@dalgo/core`](https://www.npmjs.com/package/@dalgo/core) database contracts with
+Firebase's modular Cloud Firestore Web SDK. It is intended for browser apps,
+including apps that query an OpenVaultDB Firestore database directly.
+
+## Install
+
+```sh
+pnpm add @dalgo/core @dalgo/firestore firebase
+```
+
+The adapter uses the separately published `@dalgo/core` contracts.
+
+## Browser setup
+
+```ts
+import { initializeApp } from "firebase/app";
+import { getFirestore } from "firebase/firestore";
+import { collection, key } from "@dalgo/core";
+import { FirestoreDatabase } from "@dalgo/firestore";
+
+interface Item {
+  title: string;
+  done: boolean;
+  rank: number;
+}
+
+const app = initializeApp({
+  apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
+  authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN,
+  projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,
+});
+
+const db = new FirestoreDatabase(getFirestore(app));
+const spaceKey = key("spaces", "my-space");
+const items = collection<Item>("items").in(spaceKey);
+
+const firstPage = await db.query(
+  items.query()
+    .where("done", "==", false)
+    .orderBy("rank")
+    .limit(25)
+    .build(),
+);
+
+const secondPage = firstPage.nextCursor === undefined
+  ? undefined
+  : await db.query(
+      items.query()
+        .where("done", "==", false)
+        .orderBy("rank")
+        .startAfter(...firstPage.nextCursor.values)
+        .limit(25)
+        .build(),
+);
+```
+
+For a named Firestore database, pass its database ID to `getFirestore`:
+
+```ts
+const db = new FirestoreDatabase(getFirestore(app, openVaultDatabaseId));
+```
+
+The adapter appends document ID as a deterministic final ordering field. Use
+the returned `nextCursor` rather than constructing pagination values manually.
+
+## Point reads and transactions
+
+```ts
+const item = await db.get(items.key("milk"));
+if (item.exists) {
+  console.log(item.data.title);
+}
+
+await db.runReadwriteTransaction(async (tx) => {
+  const current = await tx.get<Item>(items.key("milk"));
+  if (current.exists) {
+    await tx.update(current.key, { done: true });
+  }
+});
+```
+
+Firestore may retry a transaction callback. Keep it idempotent and do not
+perform UI or other external side effects inside it. Firestore also requires
+all reads before writes; the adapter reports a DALgo `UnsupportedError` when a
+callback tries to read after writing.
+
+## OpenVaultDB and browser security
+
+The Firebase Web configuration identifies a project; it is not an admin
+credential. Browser access must be authorized with Firebase Authentication and
+least-privilege Firestore Security Rules. Every mobile/web SDK request is
+checked by those rules. Consider Firebase App Check as an additional abuse
+signal. Never ship service-account credentials or server SDK credentials to a
+browser.
+
+This package deliberately uses the Web SDK, not `firebase-admin`, so it cannot
+bypass Firestore Security Rules.
+
+## Supported query surface
+
+- nested collections and collection-group queries
+- Firestore comparison, membership, and array filters
+- multiple `where` clauses combined with AND
+- ascending and descending ordering
+- deterministic value-cursor pagination
+- limits
+
+Offset is rejected explicitly because the Firestore Web SDK does not expose an
+offset constraint. Firestore index and operator-combination requirements remain
+native Firestore behavior and errors.
+
+## License
+
+MIT

package/dist/database.d.ts

@@ -0,0 +1,11 @@
+import { Key, type Codec, type Database, type QueryPage, type ReadwriteTransaction, type RecordSnapshot, type StructuredQuery } from "@dalgo/core";
+import { type Firestore } from "firebase/firestore";
+export declare class FirestoreDatabase implements Database {
+    readonly firestore: Firestore;
+    constructor(firestore: Firestore);
+    get<T>(key: Key, codec?: Codec<T>): Promise<RecordSnapshot<T>>;
+    getMany<T>(keys: readonly Key[], codec?: Codec<T>): Promise<readonly RecordSnapshot<T>[]>;
+    query<T>(dalQuery: StructuredQuery<T>): Promise<QueryPage<T>>;
+    runReadwriteTransaction<Result>(callback: (transaction: ReadwriteTransaction) => Promise<Result>): Promise<Result>;
+}
+//# sourceMappingURL=database.d.ts.map

package/dist/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,GAAG,EAGH,KAAK,KAAK,EACV,KAAK,QAAQ,EAEb,KAAK,SAAS,EACd,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,eAAe,EAErB,MAAM,aAAa,CAAC;AACrB,OAAO,EAQL,KAAK,SAAS,EAIf,MAAM,oBAAoB,CAAC;AAuG5B,qBAAa,iBAAkB,YAAW,QAAQ;IAChD,SAAgB,SAAS,EAAE,SAAS,CAAC;gBAElB,SAAS,EAAE,SAAS;IAI1B,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAK9D,OAAO,CAAC,CAAC,EACpB,IAAI,EAAE,SAAS,GAAG,EAAE,EACpB,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,GACf,OAAO,CAAC,SAAS,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;IAI3B,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAoBnE,uBAAuB,CAAC,MAAM,EACnC,QAAQ,EAAE,CAAC,WAAW,EAAE,oBAAoB,KAAK,OAAO,CAAC,MAAM,CAAC,GAC/D,OAAO,CAAC,MAAM,CAAC;CAKnB"}

package/dist/database.js

@@ -0,0 +1,111 @@
+import { AlreadyExistsError, Key, UnsupportedError, identityCodec, } from "@dalgo/core";
+import { doc, getDoc, getDocs, runTransaction, } from "firebase/firestore";
+import { keyFromDocumentPath } from "./path.js";
+import { compileFirestoreQuery, cursorFromSnapshot } from "./query.js";
+function codecOrIdentity(codec) {
+    return (codec ?? identityCodec);
+}
+function documentReference(firestore, key) {
+    return doc(firestore, key.path);
+}
+function recordFromSnapshot(snapshot, requestedKey, codec) {
+    const key = requestedKey ?? keyFromDocumentPath(snapshot.ref.path);
+    const metadata = {
+        fromCache: snapshot.metadata.fromCache,
+        hasPendingWrites: snapshot.metadata.hasPendingWrites,
+    };
+    if (!snapshot.exists()) {
+        return { key, exists: false, metadata };
+    }
+    return {
+        key,
+        exists: true,
+        data: codecOrIdentity(codec).decode(snapshot.data()),
+        metadata,
+    };
+}
+class FirestoreReadwriteTransaction {
+    #firestore;
+    #transaction;
+    #hasWrites = false;
+    constructor(firestore, transaction) {
+        this.#firestore = firestore;
+        this.#transaction = transaction;
+    }
+    async get(key, codec) {
+        this.assertCanRead();
+        const snapshot = await this.#transaction.get(documentReference(this.#firestore, key));
+        return recordFromSnapshot(snapshot, key, codec);
+    }
+    async getMany(keys, codec) {
+        const records = [];
+        for (const key of keys) {
+            records.push(await this.get(key, codec));
+        }
+        return records;
+    }
+    async insert(key, data, codec) {
+        const existing = await this.get(key);
+        if (existing.exists) {
+            throw new AlreadyExistsError(key);
+        }
+        this.#transaction.set(documentReference(this.#firestore, key), codecOrIdentity(codec).encode(data));
+        this.#hasWrites = true;
+    }
+    set(key, data, codec) {
+        this.#transaction.set(documentReference(this.#firestore, key), codecOrIdentity(codec).encode(data));
+        this.#hasWrites = true;
+        return Promise.resolve();
+    }
+    update(key, data) {
+        this.#transaction.update(documentReference(this.#firestore, key), data);
+        this.#hasWrites = true;
+        return Promise.resolve();
+    }
+    delete(key) {
+        this.#transaction.delete(documentReference(this.#firestore, key));
+        this.#hasWrites = true;
+        return Promise.resolve();
+    }
+    assertCanRead() {
+        if (this.#hasWrites) {
+            throw new UnsupportedError("Firestore transaction reads after writes");
+        }
+    }
+}
+export class FirestoreDatabase {
+    firestore;
+    constructor(firestore) {
+        this.firestore = firestore;
+    }
+    async get(key, codec) {
+        const snapshot = await getDoc(documentReference(this.firestore, key));
+        return recordFromSnapshot(snapshot, key, codec);
+    }
+    async getMany(keys, codec) {
+        return Promise.all(keys.map(async (key) => this.get(key, codec)));
+    }
+    async query(dalQuery) {
+        const compiled = compileFirestoreQuery(this.firestore, dalQuery);
+        const snapshot = await getDocs(compiled.query);
+        const records = snapshot.docs.map((document) => {
+            const record = recordFromSnapshot(document, undefined, dalQuery.source.codec);
+            if (!record.exists) {
+                throw new Error(`query returned a missing Firestore document: ${document.ref.path}`);
+            }
+            return record;
+        });
+        const last = snapshot.docs.at(-1);
+        const nextCursor = dalQuery.limit !== undefined && snapshot.size === dalQuery.limit && last !== undefined
+            ? cursorFromSnapshot(last, compiled.orders)
+            : undefined;
+        return {
+            records,
+            ...(nextCursor === undefined ? {} : { nextCursor }),
+        };
+    }
+    runReadwriteTransaction(callback) {
+        return runTransaction(this.firestore, async (transaction) => callback(new FirestoreReadwriteTransaction(this.firestore, transaction)));
+    }
+}
+//# sourceMappingURL=database.js.map

package/dist/database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./database.js";
+export * from "./path.js";
+export * from "./query.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./database.js";
+export * from "./path.js";
+export * from "./query.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC"}

package/dist/path.d.ts

@@ -0,0 +1,4 @@
+import { Key, type CollectionSource } from "@dalgo/core";
+export declare function firestoreCollectionPath<T>(source: CollectionSource<T>): string;
+export declare function keyFromDocumentPath(path: string): Key<string>;
+//# sourceMappingURL=path.d.ts.map

package/dist/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEzD,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,MAAM,CAI9E;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAoB7D"}

package/dist/path.js

@@ -0,0 +1,26 @@
+import { Key } from "@dalgo/core";
+export function firestoreCollectionPath(source) {
+    return source.parent === undefined
+        ? source.name
+        : `${source.parent.path}/${source.name}`;
+}
+export function keyFromDocumentPath(path) {
+    const segments = path.split("/");
+    if (segments.length === 0 || segments.length % 2 !== 0 || segments.some((part) => part === "")) {
+        throw new TypeError(`invalid Firestore document path: ${path}`);
+    }
+    let current;
+    for (let index = 0; index < segments.length; index += 2) {
+        const collection = segments[index];
+        const id = segments[index + 1];
+        if (collection === undefined || id === undefined) {
+            throw new TypeError(`invalid Firestore document path: ${path}`);
+        }
+        current = new Key(collection, id, current);
+    }
+    if (current === undefined) {
+        throw new TypeError(`invalid Firestore document path: ${path}`);
+    }
+    return current;
+}
+//# sourceMappingURL=path.js.map

package/dist/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAyB,MAAM,aAAa,CAAC;AAEzD,MAAM,UAAU,uBAAuB,CAAI,MAA2B;IACpE,OAAO,MAAM,CAAC,MAAM,KAAK,SAAS;QAChC,CAAC,CAAC,MAAM,CAAC,IAAI;QACb,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,EAAE,CAAC;QAC/F,MAAM,IAAI,SAAS,CAAC,oCAAoC,IAAI,EAAE,CAAC,CAAC;IAClE,CAAC;IAED,IAAI,OAAgC,CAAC;IACrC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACxD,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QACnC,MAAM,EAAE,GAAG,QAAQ,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QAC/B,IAAI,UAAU,KAAK,SAAS,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;YACjD,MAAM,IAAI,SAAS,CAAC,oCAAoC,IAAI,EAAE,CAAC,CAAC;QAClE,CAAC;QACD,OAAO,GAAG,IAAI,GAAG,CAAC,UAAU,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;IAC7C,CAAC;IAED,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,IAAI,SAAS,CAAC,oCAAoC,IAAI,EAAE,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/query.d.ts

@@ -0,0 +1,10 @@
+import { type QueryCursor, type QueryOrder, type QuerySource, type StructuredQuery } from "@dalgo/core";
+import { type DocumentSnapshot, type Firestore, type Query } from "firebase/firestore";
+export interface CompiledFirestoreQuery<T> {
+    readonly query: Query;
+    readonly orders: readonly QueryOrder<T>[];
+}
+export declare function toFirestoreDocumentIdValue<T>(value: unknown, source: QuerySource<T>): unknown;
+export declare function compileFirestoreQuery<T>(firestore: Firestore, dalQuery: StructuredQuery<T>): CompiledFirestoreQuery<T>;
+export declare function cursorFromSnapshot<T>(snapshot: DocumentSnapshot, orders: readonly QueryOrder<T>[]): QueryCursor;
+//# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAYL,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,KAAK,EAEX,MAAM,oBAAoB,CAAC;AAG5B,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;CAC3C;AAMD,wBAAgB,0BAA0B,CAAC,CAAC,EAC1C,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GACrB,OAAO,CAsBT;AA2BD,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,GAC3B,sBAAsB,CAAC,CAAC,CAAC,CAmC3B;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,GAC/B,WAAW,CAMb"}

package/dist/query.js

@@ -0,0 +1,73 @@
+import { DOCUMENT_ID, Key, UnsupportedError, } from "@dalgo/core";
+import { collection, collectionGroup, documentId, endAt, endBefore, limit, orderBy, query as createQuery, startAfter, startAt, where, } from "firebase/firestore";
+import { firestoreCollectionPath } from "./path.js";
+function firestoreField(field) {
+    return field === DOCUMENT_ID ? documentId() : field;
+}
+export function toFirestoreDocumentIdValue(value, source) {
+    if (value instanceof Key) {
+        if (source.kind === "collection") {
+            const collectionPath = firestoreCollectionPath(source);
+            if (value.collectionPath !== collectionPath) {
+                throw new TypeError(`document key belongs to ${value.collectionPath}, expected ${collectionPath}`);
+            }
+            return value.path.slice(collectionPath.length + 1);
+        }
+        if (value.collection !== source.name) {
+            throw new TypeError(`document key belongs to ${value.collection}, expected collection group ${source.name}`);
+        }
+        return value.path;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => toFirestoreDocumentIdValue(item, source));
+    }
+    return value;
+}
+function queryOrders(dalQuery) {
+    if (dalQuery.orders.some(({ field }) => field === DOCUMENT_ID)) {
+        return dalQuery.orders;
+    }
+    const direction = dalQuery.orders.at(-1)?.direction ?? "asc";
+    return [...dalQuery.orders, { field: DOCUMENT_ID, direction }];
+}
+function addCursor(constraints, value, orderCount, createConstraint) {
+    if (value === undefined) {
+        return;
+    }
+    if (value.values.length !== orderCount) {
+        throw new TypeError(`cursor has ${value.values.length.toString()} values but the compiled query has ${orderCount.toString()} order fields`);
+    }
+    constraints.push(createConstraint(...value.values));
+}
+export function compileFirestoreQuery(firestore, dalQuery) {
+    if ((dalQuery.offset ?? 0) !== 0) {
+        throw new UnsupportedError("Firestore Web SDK query offsets");
+    }
+    const source = dalQuery.source.kind === "collection"
+        ? collection(firestore, firestoreCollectionPath(dalQuery.source))
+        : collectionGroup(firestore, dalQuery.source.name);
+    const constraints = [];
+    for (const filter of dalQuery.filters) {
+        constraints.push(where(firestoreField(filter.field), filter.operator, filter.field === DOCUMENT_ID
+            ? toFirestoreDocumentIdValue(filter.value, dalQuery.source)
+            : filter.value));
+    }
+    const orders = queryOrders(dalQuery);
+    for (const order of orders) {
+        constraints.push(orderBy(firestoreField(order.field), order.direction));
+    }
+    addCursor(constraints, dalQuery.startAt, orders.length, startAt);
+    addCursor(constraints, dalQuery.startAfter, orders.length, startAfter);
+    addCursor(constraints, dalQuery.endAt, orders.length, endAt);
+    addCursor(constraints, dalQuery.endBefore, orders.length, endBefore);
+    if (dalQuery.limit !== undefined) {
+        constraints.push(limit(dalQuery.limit));
+    }
+    return { query: createQuery(source, ...constraints), orders };
+}
+export function cursorFromSnapshot(snapshot, orders) {
+    return {
+        values: orders.map(({ field }) => (field === DOCUMENT_ID ? snapshot.id : snapshot.get(field))),
+    };
+}
+//# sourceMappingURL=query.js.map

package/dist/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@dalgo/firestore",
+  "version": "0.1.0",
+  "description": "Firestore Web SDK adapter for DALgo TypeScript",
+  "type": "module",
+  "packageManager": "pnpm@11.20.0",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "eslint . && vitest run --exclude test/firestore.integration.test.ts && tsc -p tsconfig.build.json",
+    "lint": "eslint .",
+    "prepack": "npm run build",
+    "test": "vitest run --exclude test/firestore.integration.test.ts",
+    "test:emulator": "pnpm --package firebase-tools@15.30.2 dlx firebase emulators:exec --only firestore --project demo-dalgo-js-e2e \"vitest run test/firestore.integration.test.ts\"",
+    "test:watch": "vitest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dal-go/dalgo-http-adapters.git",
+    "directory": "packages/firestore"
+  },
+  "bugs": {
+    "url": "https://github.com/dal-go/dalgo-http-adapters/issues"
+  },
+  "homepage": "https://github.com/dal-go/dalgo-http-adapters/tree/main/packages/firestore#readme",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@dalgo/core": "^0.1.0",
+    "firebase": "^12.19.0"
+  },
+  "devDependencies": {
+    "@dalgo/core": "^0.1.0",
+    "@eslint/js": "10.0.1",
+    "eslint": "10.11.0",
+    "firebase": "12.19.0",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.70.0",
+    "vitest": "5.0.1"
+  }
+}