svelte-firekit 0.1.8 → 0.2.0

package/dist/services/bundles.d.ts

@@ -0,0 +1,42 @@
+import { type Query, type DocumentData } from 'firebase/firestore';
+/**
+ * Loads a Firestore bundle into the local cache.
+ *
+ * Bundles are pre-packaged snapshots of query results generated server-side,
+ * which lets you serve initial data from CDN/cache instead of hitting Firestore.
+ *
+ * After loading, use `getNamedQuery()` to retrieve a cached query and pass it
+ * to `FirekitCollection` or `getDocs`.
+ *
+ * @param data  The bundle data — a `ReadableStream<Uint8Array>`, `ArrayBuffer`, or `string`.
+ * @returns     Total number of documents loaded from the bundle.
+ *
+ * @example
+ * ```ts
+ * import { loadFirestoreBundle, getNamedQuery } from 'svelte-firekit';
+ * import { getDocs } from 'firebase/firestore';
+ *
+ * const res = await fetch('/bundles/featured-posts.bundle');
+ * await loadFirestoreBundle(res.body!);
+ *
+ * const q = await getNamedQuery('featured-posts');
+ * if (q) {
+ *   const snap = await getDocs(q);
+ * }
+ * ```
+ */
+export declare function loadFirestoreBundle(data: ReadableStream<Uint8Array> | ArrayBuffer | string): Promise<number>;
+/**
+ * Retrieves a named query that was loaded via `loadFirestoreBundle()`.
+ *
+ * Returns `null` if the named query has not been loaded yet.
+ *
+ * @example
+ * ```ts
+ * const query = await getNamedQuery<Post>('featured-posts');
+ * if (query) {
+ *   const snap = await getDocs(query);
+ * }
+ * ```
+ */
+export declare function getNamedQuery<T = DocumentData>(queryName: string): Promise<Query<T> | null>;

package/dist/services/bundles.js

@@ -0,0 +1,57 @@
+import { loadBundle, namedQuery } from 'firebase/firestore';
+import { firebaseService } from '../firebase.js';
+function getDb() {
+    const db = firebaseService.getDbInstance();
+    if (!db)
+        throw new Error('Firestore is not initialized.');
+    return db;
+}
+/**
+ * Loads a Firestore bundle into the local cache.
+ *
+ * Bundles are pre-packaged snapshots of query results generated server-side,
+ * which lets you serve initial data from CDN/cache instead of hitting Firestore.
+ *
+ * After loading, use `getNamedQuery()` to retrieve a cached query and pass it
+ * to `FirekitCollection` or `getDocs`.
+ *
+ * @param data  The bundle data — a `ReadableStream<Uint8Array>`, `ArrayBuffer`, or `string`.
+ * @returns     Total number of documents loaded from the bundle.
+ *
+ * @example
+ * ```ts
+ * import { loadFirestoreBundle, getNamedQuery } from 'svelte-firekit';
+ * import { getDocs } from 'firebase/firestore';
+ *
+ * const res = await fetch('/bundles/featured-posts.bundle');
+ * await loadFirestoreBundle(res.body!);
+ *
+ * const q = await getNamedQuery('featured-posts');
+ * if (q) {
+ *   const snap = await getDocs(q);
+ * }
+ * ```
+ */
+export async function loadFirestoreBundle(data) {
+    const db = getDb();
+    const result = await loadBundle(db, data);
+    return result.totalDocuments;
+}
+/**
+ * Retrieves a named query that was loaded via `loadFirestoreBundle()`.
+ *
+ * Returns `null` if the named query has not been loaded yet.
+ *
+ * @example
+ * ```ts
+ * const query = await getNamedQuery<Post>('featured-posts');
+ * if (query) {
+ *   const snap = await getDocs(query);
+ * }
+ * ```
+ */
+export async function getNamedQuery(queryName) {
+    const db = getDb();
+    const result = await namedQuery(db, queryName);
+    return result;
+}

package/dist/services/callable.d.ts

@@ -0,0 +1,57 @@
+import { type HttpsCallableOptions } from 'firebase/functions';
+/**
+ * A typed callable Cloud Function wrapper with reactive loading/error state.
+ *
+ * Wraps `httpsCallable` and tracks in-flight state so you can bind it
+ * directly to a UI without managing state yourself.
+ *
+ * @example
+ * ```ts
+ * import { firekitCallable } from 'svelte-firekit';
+ *
+ * const sendWelcomeEmail = firekitCallable<{ userId: string }, { sent: boolean }>('sendWelcomeEmail');
+ * const result = await sendWelcomeEmail.call({ userId: 'abc' });
+ * ```
+ */
+export declare class FirekitCallable<TData = unknown, TResult = unknown> {
+    protected _loading: boolean;
+    protected _error: Error | null;
+    protected _result: TResult | null;
+    readonly called: boolean;
+    protected _name: string;
+    protected _options: HttpsCallableOptions | undefined;
+    constructor(name: string, options?: HttpsCallableOptions);
+    get loading(): boolean;
+    get error(): Error | null;
+    get result(): TResult | null;
+    /**
+     * Calls the Cloud Function with the given data.
+     * Returns the result data, or null on error.
+     */
+    call(data?: TData): Promise<TResult | null>;
+    /** Resets result and error state. */
+    reset(): void;
+}
+/**
+ * A typed callable Cloud Function wrapper that calls a function by URL
+ * (useful for non-default regions or emulator overrides).
+ */
+export declare class FirekitCallableFromURL<TData = unknown, TResult = unknown> extends FirekitCallable<TData, TResult> {
+    private _url;
+    constructor(url: string, options?: HttpsCallableOptions);
+    call(data?: TData): Promise<TResult | null>;
+}
+/**
+ * Creates a typed callable Cloud Function wrapper.
+ *
+ * @example
+ * ```ts
+ * const calculateShipping = firekitCallable<{ cartId: string }, { cost: number }>('calculateShipping');
+ * const result = await calculateShipping.call({ cartId: 'abc' });
+ * ```
+ */
+export declare function firekitCallable<TData = unknown, TResult = unknown>(name: string, options?: HttpsCallableOptions): FirekitCallable<TData, TResult>;
+/**
+ * Creates a typed callable Cloud Function wrapper using a direct URL.
+ */
+export declare function firekitCallableFromURL<TData = unknown, TResult = unknown>(url: string, options?: HttpsCallableOptions): FirekitCallableFromURL<TData, TResult>;

package/dist/services/callable.js

@@ -0,0 +1,115 @@
+import { httpsCallable, httpsCallableFromURL } from 'firebase/functions';
+import { firebaseService } from '../firebase.js';
+function getFunctions() {
+    const fn = firebaseService.getFunctionsInstance();
+    if (!fn)
+        throw new Error('Firebase Functions is not initialized.');
+    return fn;
+}
+/**
+ * A typed callable Cloud Function wrapper with reactive loading/error state.
+ *
+ * Wraps `httpsCallable` and tracks in-flight state so you can bind it
+ * directly to a UI without managing state yourself.
+ *
+ * @example
+ * ```ts
+ * import { firekitCallable } from 'svelte-firekit';
+ *
+ * const sendWelcomeEmail = firekitCallable<{ userId: string }, { sent: boolean }>('sendWelcomeEmail');
+ * const result = await sendWelcomeEmail.call({ userId: 'abc' });
+ * ```
+ */
+export class FirekitCallable {
+    _loading = $state(false);
+    _error = $state(null);
+    _result = $state(null);
+    called = $derived(this._result !== null || this._error !== null);
+    _name;
+    _options;
+    constructor(name, options) {
+        this._name = name;
+        this._options = options;
+    }
+    get loading() { return this._loading; }
+    get error() { return this._error; }
+    get result() { return this._result; }
+    /**
+     * Calls the Cloud Function with the given data.
+     * Returns the result data, or null on error.
+     */
+    async call(data) {
+        if (!this._name) {
+            throw new Error('Cannot call a Cloud Function with an empty name. Use FirekitCallableFromURL instead.');
+        }
+        this._loading = true;
+        this._error = null;
+        try {
+            const fn = getFunctions();
+            const callable = httpsCallable(fn, this._name, this._options);
+            const res = await callable(data);
+            this._result = res.data;
+            return res.data;
+        }
+        catch (err) {
+            this._error = err instanceof Error ? err : new Error(String(err));
+            return null;
+        }
+        finally {
+            this._loading = false;
+        }
+    }
+    /** Resets result and error state. */
+    reset() {
+        this._result = null;
+        this._error = null;
+    }
+}
+/**
+ * A typed callable Cloud Function wrapper that calls a function by URL
+ * (useful for non-default regions or emulator overrides).
+ */
+export class FirekitCallableFromURL extends FirekitCallable {
+    _url;
+    constructor(url, options) {
+        super('', options);
+        this._url = url;
+    }
+    async call(data) {
+        this._loading = true;
+        this._error = null;
+        try {
+            const fn = getFunctions();
+            const callable = httpsCallableFromURL(fn, this._url, this._options);
+            const res = await callable(data);
+            this._result = res.data;
+            return res.data;
+        }
+        catch (err) {
+            this._error = err instanceof Error ? err : new Error(String(err));
+            return null;
+        }
+        finally {
+            this._loading = false;
+        }
+    }
+}
+// ── Factory functions ─────────────────────────────────────────────────────────
+/**
+ * Creates a typed callable Cloud Function wrapper.
+ *
+ * @example
+ * ```ts
+ * const calculateShipping = firekitCallable<{ cartId: string }, { cost: number }>('calculateShipping');
+ * const result = await calculateShipping.call({ cartId: 'abc' });
+ * ```
+ */
+export function firekitCallable(name, options) {
+    return new FirekitCallable(name, options);
+}
+/**
+ * Creates a typed callable Cloud Function wrapper using a direct URL.
+ */
+export function firekitCallableFromURL(url, options) {
+    return new FirekitCallableFromURL(url, options);
+}