@sovaria/sdk 0.0.0-stage → 0.5.0

package/dist/firestore.js

@@ -0,0 +1,431 @@
+/**
+ * Firebase Firestore's modular API on Sovaria documents: move a Firebase app by changing imports.
+ *
+ * ```ts
+ * // before: import { getFirestore, collection, query, where, getDocs, … } from 'firebase/firestore'
+ * import { getFirestore, collection, query, where, orderBy, limit, getDocs, onSnapshot,
+ *          doc, setDoc, updateDoc, increment, serverTimestamp, runTransaction } from '@sovaria/sdk/firestore'
+ *
+ * const db = getFirestore(sov)              // sov = createClient(...)
+ * const q = query(collection(db, 'posts'), where('room', '==', 'r1'), orderBy('at', 'desc'), limit(20))
+ * const snap = await getDocs(q)
+ * snap.forEach((d) => console.log(d.id, d.data()))
+ * const stop = onSnapshot(q, (s) => render(s.docs.map((d) => d.data())))
+ * await updateDoc(doc(db, 'posts', 'p1'), { likes: increment(1), at: serverTimestamp() })
+ * ```
+ *
+ * Collection groups and vector search work too:
+ *
+ * ```ts
+ * const flagged = await getDocs(query(collectionGroup(db, 'comments'), where('flagged', '==', true)))
+ * const near = await getDocs(findNearest(collection(db, 'items'), {
+ *   vectorField: 'embedding', queryVector: vector([0.1, 0.2, 0.3]), limit: 5, distanceMeasure: 'COSINE' }))
+ * ```
+ *
+ * The functions keep Firebase's names, arguments and object shapes (`snap.data()`, `snap.exists()`,
+ * `docChanges()`, `onSnapshot` returning its unsubscribe function at once). Underneath it is the
+ * Sovaria collection API, so collection rules and row policies decide every read and write.
+ * Differences: timestamps are stored as ISO-8601 strings (`Timestamp` and `Date` values you write are
+ * converted), there is no offline cache, and `getDocFromCache` / persistence settings don't exist.
+ */
+import { SovariaError } from './errors.js';
+import { FieldValue, } from './collections.js';
+/** What getFirestore needs from a Sovaria client (any `SovariaSDK`). */
+import { indexedDbStorage, memoryStorage } from './offline.js';
+export class Firestore {
+    sov;
+    type = 'firestore';
+    constructor(sov) {
+        this.sov = sov;
+    }
+}
+/** The Firestore handle for a Sovaria client. */
+export function getFirestore(sov) {
+    return new Firestore(sov);
+}
+/** Firebase's `persistentLocalCache()`: IndexedDB in browsers (memory where there is none). */
+export function persistentLocalCache(options = {}) {
+    let storage = options.storage;
+    if (!storage) {
+        try {
+            storage = indexedDbStorage();
+        }
+        catch {
+            storage = memoryStorage();
+        }
+    }
+    return { kind: 'persistent', storage };
+}
+/** Firebase's `memoryLocalCache()`: offline cache for this page/process only. */
+export function memoryLocalCache() {
+    return { kind: 'memory', storage: memoryStorage() };
+}
+/** `initializeFirestore(sov, { localCache: persistentLocalCache() })` turns on offline mode, like Firebase. */
+export function initializeFirestore(sov, settings = {}) {
+    if (settings.localCache)
+        enableOffline(sov, settings.localCache.storage);
+    return new Firestore(sov);
+}
+/** Firebase's (older) way to turn on the persistent cache. */
+export async function enableIndexedDbPersistence(db) {
+    enableOffline(db.sov, persistentLocalCache().storage);
+}
+function enableOffline(sov, storage) {
+    const target = sov;
+    if (typeof target.enableOffline !== 'function') {
+        throw new Error('This Sovaria client has no offline mode (update @sovaria/sdk)');
+    }
+    target.enableOffline({ storage });
+}
+function join(path, segments) {
+    return [path, ...segments].join('/').split('/').filter(Boolean).join('/');
+}
+// ── references ────────────────────────────────────────────────────────────────
+export class DocumentReference {
+    firestore;
+    _ref;
+    type = 'document';
+    constructor(firestore, _ref) {
+        this.firestore = firestore;
+        this._ref = _ref;
+    }
+    get id() { return this._ref.id; }
+    get path() { return this._ref.path; }
+    get parent() {
+        return new CollectionReference(this.firestore, this.firestore.sov.collection(this.path.split('/').slice(0, -1).join('/')));
+    }
+}
+export class Query {
+    firestore;
+    _query;
+    type = 'query';
+    constructor(firestore, _query) {
+        this.firestore = firestore;
+        this._query = _query;
+    }
+    /** Vector search, Admin-SDK style: `collection(db, 'items').findNearest({...}).get()`. */
+    findNearest(options) {
+        return findNearest(this, options);
+    }
+}
+/** A vector value (Firebase `vector([...])`); stored as an array of numbers. */
+export class VectorValue {
+    type = 'vector';
+    values;
+    constructor(values) { this.values = values.map(Number); }
+    toArray() { return [...this.values]; }
+    isEqual(other) {
+        const a = other.toArray();
+        return a.length === this.values.length && a.every((v, i) => v === this.values[i]);
+    }
+}
+export function vector(values) {
+    return new VectorValue(values);
+}
+/** A nearest-neighbour query; read it with `getDocs(vq)` or `vq.get()`. */
+export class VectorQuery {
+    firestore;
+    _vector;
+    type = 'vectorQuery';
+    constructor(firestore, _vector) {
+        this.firestore = firestore;
+        this._vector = _vector;
+    }
+    get() { return getDocs(this); }
+}
+/** Firestore `findNearest`: the query's filters first, then the `limit` closest documents (closest first). */
+export function findNearest(q, options) {
+    const queryVector = options.queryVector instanceof VectorValue ? options.queryVector.toArray() : options.queryVector;
+    return new VectorQuery(q.firestore, q._query.findNearest({
+        vectorField: options.vectorField,
+        queryVector,
+        limit: options.limit,
+        distanceMeasure: options.distanceMeasure ?? 'COSINE',
+        distanceResultField: options.distanceResultField,
+        distanceThreshold: options.distanceThreshold,
+    }));
+}
+export class CollectionReference extends Query {
+    type = 'collection';
+    get id() { return this._query.id; }
+    get path() { return this._query.path; }
+}
+/** `collection(db, 'users')`, `collection(db, 'users', uid, 'posts')`, `collection(docRef, 'posts')`. */
+export function collection(parent, path, ...segments) {
+    const base = parent instanceof Firestore ? '' : parent.path;
+    const db = parent instanceof Firestore ? parent : parent.firestore;
+    return new CollectionReference(db, db.sov.collection(join(base ? `${base}/${path}` : path, segments)));
+}
+/** Every collection with this id at any depth (`comments`, `posts/p1/comments`, …). */
+export function collectionGroup(db, collectionId) {
+    if (collectionId.includes('/'))
+        throw SovariaError.config(`collectionGroup('${collectionId}'): a collection id, not a path`);
+    if (typeof db.sov.collectionGroup !== 'function')
+        throw SovariaError.config('This Sovaria client has no collectionGroup (update @sovaria/sdk)');
+    return new Query(db, db.sov.collectionGroup(collectionId));
+}
+/** `doc(db, 'users', uid)`, `doc(db, 'users/uid')`, `doc(collectionRef)` (new id), `doc(collectionRef, id)`. */
+export function doc(parent, path, ...segments) {
+    if (parent instanceof CollectionReference) {
+        const ref = path === undefined ? parent._query.doc() : parent._query.doc(join(path, segments));
+        return new DocumentReference(parent.firestore, ref);
+    }
+    const base = parent instanceof Firestore ? '' : parent.path;
+    const db = parent instanceof Firestore ? parent : parent.firestore;
+    if (path === undefined)
+        throw SovariaError.config('doc() needs a path');
+    return new DocumentReference(db, db.sov.doc(join(base ? `${base}/${path}` : path, segments)));
+}
+/** `where(documentId(), '==', id)` filters on the document id. */
+export function documentId() {
+    return '__key__';
+}
+function filterConstraint(filter) {
+    return Object.assign((q) => q.where(filter), { _filter: filter });
+}
+export function where(field, op, value) {
+    return filterConstraint([field, op, toWire(value)]);
+}
+/** Firebase `or()`: documents matching any of the filters (at most 30 OR terms after expansion). */
+export function or(...filters) {
+    return filterConstraint({ or: filters.map((f) => f._filter) });
+}
+/** Firebase `and()`: documents matching all of the filters, for nesting inside `or()`. */
+export function and(...filters) {
+    return filterConstraint({ and: filters.map((f) => f._filter) });
+}
+export function orderBy(field, direction = 'asc') {
+    return (q) => q.orderBy(field, direction);
+}
+export function limit(n) {
+    return (q) => q.limit(n);
+}
+export function limitToLast(n) {
+    return (q) => q.limitToLast(n);
+}
+function cursorArgs(values) {
+    const [first] = values;
+    if (values.length === 1 && first instanceof DocumentSnapshot)
+        return [first._snap];
+    return values.map(toWire);
+}
+export function startAt(...values) { return (q) => q.startAt(...cursorArgs(values)); }
+export function startAfter(...values) { return (q) => q.startAfter(...cursorArgs(values)); }
+export function endAt(...values) { return (q) => q.endAt(...cursorArgs(values)); }
+export function endBefore(...values) { return (q) => q.endBefore(...cursorArgs(values)); }
+export function query(base, ...constraints) {
+    let q = base._query;
+    for (const c of constraints)
+        q = c(q);
+    return new Query(base.firestore, q);
+}
+// ── snapshots ─────────────────────────────────────────────────────────────────
+export class DocumentSnapshot {
+    ref;
+    _snap;
+    constructor(ref, _snap) {
+        this.ref = ref;
+        this._snap = _snap;
+    }
+    get id() { return this._snap.id; }
+    exists() { return this._snap.exists; }
+    data() { return this._snap.exists ? this._snap.data : undefined; }
+    /** A field by dotted path (`get('address.city')`). */
+    get(field) {
+        let value = this._snap.data;
+        for (const part of field.split('.'))
+            value = value == null ? undefined : value[part];
+        return value;
+    }
+    /** Offline mode (enableIndexedDbPersistence / persistentLocalCache): from the cache, or a write not yet synced. */
+    get metadata() { return { hasPendingWrites: Boolean(this._snap.hasPendingWrites), fromCache: Boolean(this._snap.fromCache) }; }
+}
+export class QueryDocumentSnapshot extends DocumentSnapshot {
+    data() { return this._snap.data; }
+}
+export class QuerySnapshot {
+    query;
+    docs;
+    changes;
+    constructor(query, raw) {
+        this.query = query;
+        const wrap = (s) => new QueryDocumentSnapshot(new DocumentReference(query.firestore, query.firestore.sov.doc(s.path)), s);
+        this.docs = raw.docs.map(wrap);
+        this.changes = raw.changes.map((c) => ({ type: c.type, doc: wrap(c.doc), oldIndex: c.oldIndex, newIndex: c.newIndex }));
+    }
+    get size() { return this.docs.length; }
+    get empty() { return this.docs.length === 0; }
+    forEach(callback) { this.docs.forEach(callback); }
+    docChanges() { return this.changes; }
+    /** Offline mode: answered from the cache, or holding writes not yet synced. */
+    get metadata() {
+        return { hasPendingWrites: this.docs.some((d) => d.metadata.hasPendingWrites), fromCache: this.docs.some((d) => d.metadata.fromCache) };
+    }
+}
+// ── reads ─────────────────────────────────────────────────────────────────────
+export async function getDoc(ref) {
+    return new DocumentSnapshot(ref, await ref._ref.get());
+}
+export async function getDocs(q) {
+    if (q instanceof VectorQuery)
+        return new QuerySnapshot(q, await q._vector.get());
+    return new QuerySnapshot(q, await q._query.get());
+}
+export async function getCountFromServer(q) {
+    const count = await q._query.count();
+    return { data: () => ({ count }) };
+}
+/** Firebase aggregate fields for `getAggregateFromServer`. */
+export class AggregateField {
+    aggregateType;
+    _field;
+    _r;
+    type = 'AggregateField';
+    /** @internal */
+    constructor(aggregateType, _field, _r) {
+        this.aggregateType = aggregateType;
+        this._field = _field;
+        this._r = _r;
+    }
+}
+export function count() { return new AggregateField('count'); }
+export function sum(field) { return new AggregateField('sum', field); }
+export function average(field) { return new AggregateField('avg', field); }
+/** Firebase `getAggregateFromServer(q, { total: sum('price'), avg: average('rating'), n: count() })`. */
+export async function getAggregateFromServer(q, spec) {
+    const out = await q._query.aggregate(Object.fromEntries(Object.entries(spec).map(([alias, f]) => [alias, f._field ? { op: f.aggregateType, field: f._field } : { op: f.aggregateType }])));
+    return { data: () => out };
+}
+export const getAggregate = getAggregateFromServer;
+/** Live document or query. Returns its unsubscribe function right away, like Firebase. */
+export function onSnapshot(target, onNextOrObserver, onError) {
+    const next = typeof onNextOrObserver === 'function' ? onNextOrObserver : onNextOrObserver.next ?? (() => undefined);
+    const error = (typeof onNextOrObserver === 'function' ? onError : onNextOrObserver.error) ?? ((e) => console.error(e));
+    let stopped = false;
+    let stop;
+    const started = target instanceof DocumentReference
+        ? target._ref.onSnapshot((s) => next(new DocumentSnapshot(target, s)), error)
+        : target._query.onSnapshot((s) => next(new QuerySnapshot(target, s)), error);
+    started.then((fn) => { if (stopped)
+        fn();
+    else
+        stop = fn; }).catch(error);
+    return () => {
+        stopped = true;
+        stop?.();
+    };
+}
+// ── writes ────────────────────────────────────────────────────────────────────
+/** A point in time. Stored as an ISO-8601 string in Sovaria. */
+export class Timestamp {
+    seconds;
+    nanoseconds;
+    constructor(seconds, nanoseconds) {
+        this.seconds = seconds;
+        this.nanoseconds = nanoseconds;
+    }
+    static now() { return Timestamp.fromMillis(Date.now()); }
+    static fromDate(date) { return Timestamp.fromMillis(date.getTime()); }
+    static fromMillis(ms) { return new Timestamp(Math.floor(ms / 1000), (ms % 1000) * 1e6); }
+    /** Read back a stored timestamp (an ISO string) as a Timestamp. */
+    static fromIso(value) { return Timestamp.fromMillis(Date.parse(value)); }
+    toMillis() { return this.seconds * 1000 + Math.floor(this.nanoseconds / 1e6); }
+    toDate() { return new Date(this.toMillis()); }
+    toISOString() { return this.toDate().toISOString(); }
+    isEqual(other) { return this.seconds === other.seconds && this.nanoseconds === other.nanoseconds; }
+}
+function toWire(value) {
+    if (value instanceof VectorValue)
+        return value.toArray();
+    if (value instanceof Timestamp)
+        return value.toISOString();
+    if (value instanceof Date)
+        return value.toISOString();
+    if (value instanceof DocumentReference)
+        return value.path;
+    if (Array.isArray(value))
+        return value.map(toWire);
+    if (value && typeof value === 'object' && !isFieldValue(value)) {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, toWire(v)]));
+    }
+    return value;
+}
+function isFieldValue(value) {
+    return Object.getOwnPropertySymbols(value).some((s) => s.description === 'sovaria.fieldValue');
+}
+export function serverTimestamp() { return FieldValue.serverTimestamp(); }
+export function increment(n) { return FieldValue.increment(n); }
+export function arrayUnion(...elements) { return FieldValue.arrayUnion(...elements.map(toWire)); }
+export function arrayRemove(...elements) { return FieldValue.arrayRemove(...elements.map(toWire)); }
+export function deleteField() { return FieldValue.delete(); }
+function updateFields(dataOrField, rest) {
+    if (typeof dataOrField !== 'string')
+        return toWire(dataOrField);
+    const fields = { [dataOrField]: toWire(rest[0]) };
+    for (let i = 1; i + 1 < rest.length; i += 2)
+        fields[String(rest[i])] = toWire(rest[i + 1]);
+    return fields;
+}
+export async function setDoc(ref, data, options = {}) {
+    await ref._ref.set(toWire(data), options);
+}
+export async function addDoc(ref, data) {
+    const created = await ref._query.add(toWire(data));
+    return new DocumentReference(ref.firestore, created);
+}
+/** `updateDoc(ref, {a: 1})` or `updateDoc(ref, 'a', 1, 'b.c', 2)`. */
+export async function updateDoc(ref, dataOrField, ...rest) {
+    await ref._ref.update(updateFields(dataOrField, rest));
+}
+export async function deleteDoc(ref) {
+    await ref._ref.delete();
+}
+export class WriteBatch {
+    batch;
+    constructor(batch) {
+        this.batch = batch;
+    }
+    set(ref, data, options = {}) {
+        this.batch.set(ref._ref, toWire(data), options);
+        return this;
+    }
+    update(ref, dataOrField, ...rest) {
+        this.batch.update(ref._ref, updateFields(dataOrField, rest));
+        return this;
+    }
+    delete(ref) {
+        this.batch.delete(ref._ref);
+        return this;
+    }
+    async commit() {
+        await this.batch.commit();
+    }
+}
+export function writeBatch(db) {
+    return new WriteBatch(db.sov.batch());
+}
+export class Transaction {
+    tx;
+    constructor(tx) {
+        this.tx = tx;
+    }
+    async get(ref) {
+        return new DocumentSnapshot(ref, await this.tx.get(ref._ref));
+    }
+    set(ref, data, options = {}) {
+        this.tx.set(ref._ref, toWire(data), options);
+        return this;
+    }
+    update(ref, dataOrField, ...rest) {
+        this.tx.update(ref._ref, updateFields(dataOrField, rest));
+        return this;
+    }
+    delete(ref) {
+        this.tx.delete(ref._ref);
+        return this;
+    }
+}
+/** Reads then writes atomically; retried when a document it read changed meanwhile (default 5 attempts). */
+export function runTransaction(db, fn, options = {}) {
+    return db.sov.runTransaction((tx) => fn(new Transaction(tx)), options.maxAttempts ?? 5);
+}