svelte-firekit 0.1.9 → 0.2.0

package/dist/services/realtime.svelte.d.ts

@@ -1,147 +1,76 @@
+import { serverTimestamp, increment, type DatabaseReference } from 'firebase/database';
 /**
- * @fileoverview FirekitRealtimeDB - Optimized Realtime Database management for Svelte applications
- * @module FirekitRealtimeDB
- * @version 1.0.0
- */
-import { type DatabaseReference } from 'firebase/database';
-/**
- * Manages real-time Firebase Realtime Database subscriptions with reactive state
- * @class
- * @template T Data type
- *
- * @example
- * ```typescript
- * interface ChatMessage {
- *   text: string;
- *   userId: string;
- *   timestamp: number;
- * }
+ * Reactive Firebase Realtime Database node subscription.
  *
- * // Create regular reference
- * const chatRef = firekitRealtimeDB<ChatMessage>('chats/123');
+ * Subscribes to a database path and exposes reactive state via Svelte 5 runes.
+ * Supports read and write operations on the same reference.
  *
- * // Create list reference
- * const messagesList = firekitRealtimeList<ChatMessage>('messages');
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { firekitNode } from 'svelte-firekit';
+ *   const chat = firekitNode<ChatMessage>('chats/room1');
+ * </script>
+ * {#if chat.loading}Loading…{/if}
+ * {#if chat.data}{chat.data.text}{/if}
  * ```
  */
-declare class FirekitRealtimeDB<T> {
-    /** Current data */
+export declare class FirekitNode<T = unknown> {
     private _data;
-    /** Loading state */
     private _loading;
-    /** Error state */
     private _error;
-    /** Database reference */
-    private dbRef;
-    /** Subscription cleanup function */
-    private unsubscribe;
-    /**
-     * Creates a Realtime Database subscription
-     * @param {string} path Database path
-     * @param {T} [startWith] Initial data before fetch completes
-     */
+    private _ref;
+    private _unsubscribe;
+    private _path;
     constructor(path: string, startWith?: T);
-    /**
-     * Initializes database subscription
-     * @private
-     * @param {string} path Database path
-     */
-    private initializeRealtimeDB;
-    /**
-     * Pushes new data to list
-     * @param {T} data Data to push
-     * @returns {Promise<string | null>} New item key or null if failed
-     *
-     * @example
-     * ```typescript
-     * const key = await chatRef.push({
-     *   text: 'Hello',
-     *   userId: '123',
-     *   timestamp: Date.now()
-     * });
-     * ```
-     */
-    push(data: T): Promise<string | null>;
-    /**
-     * Sets data at reference
-     * @param {T} data Data to set
-     *
-     * @example
-     * ```typescript
-     * await chatRef.set({
-     *   text: 'Updated message',
-     *   userId: '123',
-     *   timestamp: Date.now()
-     * });
-     * ```
-     */
-    set(data: T): Promise<void>;
-    /**
-     * Updates data at reference
-     * @param {Partial<T>} data Data to update
-     *
-     * @example
-     * ```typescript
-     * await chatRef.update({
-     *   text: 'Edited message'
-     * });
-     * ```
-     */
-    update(data: Partial<T>): Promise<void>;
-    /**
-     * Removes data at reference
-     *
-     * @example
-     * ```typescript
-     * await chatRef.remove();
-     * ```
-     */
-    remove(): Promise<void>;
-    /** Gets current data */
     get data(): T | null;
-    /** Gets loading state */
     get loading(): boolean;
-    /** Gets error state */
     get error(): Error | null;
-    /**
-     * Gets database reference
-     * @throws {Error} If reference is not available
-     */
+    get path(): string;
     get ref(): DatabaseReference;
-    /** Cleanup subscription */
+    private _init;
+    /** Pushes a new child node (list append). Returns the new key, or null on failure. */
+    push(data: T): Promise<string | null>;
+    /** Overwrites the node with new data. */
+    set(data: T): Promise<void>;
+    /** Merges partial data into the node (shallow merge). */
+    update(data: Partial<T>): Promise<void>;
+    /** Deletes the node. */
+    remove(): Promise<void>;
+    /** One-time fetch of current data (no subscription). */
+    fetchOnce(): Promise<T | null>;
+    /** Stops the real-time listener. */
     dispose(): void;
 }
 /**
- * Creates a reactive Realtime Database reference
- * @template T Data type
- * @param {string} path Database path
- * @param {T} [startWith] Initial data
- * @returns {FirekitRealtimeDB<T>} Database subscription instance
+ * Reactive RTDB list — subscribes to a node and exposes its children as
+ * a typed array with each item's key injected as `id`.
  *
  * @example
- * ```typescript
- * const chatRef = firekitRealtimeDB<ChatMessage>('chats/123');
+ * ```svelte
+ * <script lang="ts">
+ *   import { firekitNodeList } from 'svelte-firekit';
+ *   const messages = firekitNodeList<Message>('rooms/123/messages');
+ * </script>
+ * {#each messages.list as msg}
+ *   <p>{msg.id}: {msg.text}</p>
+ * {/each}
  * ```
  */
-export declare function firekitRealtimeDB<T>(path: string, startWith?: T): FirekitRealtimeDB<T>;
+export declare class FirekitNodeList<T = unknown> extends FirekitNode<Record<string, T>> {
+    readonly list: (T & {
+        id: string;
+    })[];
+}
+/** RTDB server timestamp sentinel. */
+export declare const rtdbServerTimestamp: typeof serverTimestamp;
+/** RTDB increment sentinel. */
+export declare const rtdbIncrement: typeof increment;
 /**
- * Creates a reactive Realtime Database list reference
- * Automatically converts data to array format with IDs
- *
- * @template T List item type
- * @param {string} path Database path
- * @param {T[]} [startWith=[]] Initial array data
- * @returns {FirekitRealtimeDB} Database subscription instance with array support
- *
- * @example
- * ```typescript
- * const messagesList = firekitRealtimeList<ChatMessage>('messages');
- * console.log(messagesList.list); // Array of messages with IDs
- * ```
+ * Creates a reactive RTDB node subscription.
  */
-export declare function firekitRealtimeList<T>(path: string, startWith?: T[]): FirekitRealtimeDB<Record<string, T>> & {
-    list: Array<T & {
-        id: string;
-    }>;
-};
-export {};
+export declare function firekitNode<T = unknown>(path: string, startWith?: T): FirekitNode<T>;
+/**
+ * Creates a reactive RTDB node subscription that exposes children as an array.
+ */
+export declare function firekitNodeList<T = unknown>(path: string, startWith?: T[]): FirekitNodeList<T>;

package/dist/services/realtime.svelte.js

@@ -1,221 +1,157 @@
-/**
- * @fileoverview FirekitRealtimeDB - Optimized Realtime Database management for Svelte applications
- * @module FirekitRealtimeDB
- * @version 1.0.0
- */
-import { ref, onValue, push, set, update, remove } from 'firebase/database';
+import { ref, onValue, push, set, update, remove, get, serverTimestamp, increment } from 'firebase/database';
 import { firebaseService } from '../firebase.js';
-import { browser } from '$app/environment';
+function getDb() {
+    const db = firebaseService.getDatabaseInstance();
+    if (!db)
+        throw new Error('Realtime Database is not initialized.');
+    return db;
+}
 /**
- * Manages real-time Firebase Realtime Database subscriptions with reactive state
- * @class
- * @template T Data type
- *
- * @example
- * ```typescript
- * interface ChatMessage {
- *   text: string;
- *   userId: string;
- *   timestamp: number;
- * }
+ * Reactive Firebase Realtime Database node subscription.
  *
- * // Create regular reference
- * const chatRef = firekitRealtimeDB<ChatMessage>('chats/123');
+ * Subscribes to a database path and exposes reactive state via Svelte 5 runes.
+ * Supports read and write operations on the same reference.
  *
- * // Create list reference
- * const messagesList = firekitRealtimeList<ChatMessage>('messages');
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { firekitNode } from 'svelte-firekit';
+ *   const chat = firekitNode<ChatMessage>('chats/room1');
+ * </script>
+ * {#if chat.loading}Loading…{/if}
+ * {#if chat.data}{chat.data.text}{/if}
  * ```
  */
-class FirekitRealtimeDB {
-    /** Current data */
+export class FirekitNode {
+    // ── Reactive state ────────────────────────────────────────────────────────
     _data = $state(null);
-    /** Loading state */
     _loading = $state(true);
-    /** Error state */
     _error = $state(null);
-    /** Database reference */
-    dbRef = null;
-    /** Subscription cleanup function */
-    unsubscribe = null;
-    /**
-     * Creates a Realtime Database subscription
-     * @param {string} path Database path
-     * @param {T} [startWith] Initial data before fetch completes
-     */
+    // ── Internal ──────────────────────────────────────────────────────────────
+    _ref = null;
+    _unsubscribe = null;
+    _path;
     constructor(path, startWith) {
-        this._data = startWith ?? null;
-        if (browser) {
-            this.initializeRealtimeDB(path);
-        }
+        this._path = path;
+        if (startWith !== undefined)
+            this._data = startWith;
+        this._init();
     }
-    /**
-     * Initializes database subscription
-     * @private
-     * @param {string} path Database path
-     */
-    initializeRealtimeDB(path) {
+    // ── Public getters ────────────────────────────────────────────────────────
+    get data() { return this._data; }
+    get loading() { return this._loading; }
+    get error() { return this._error; }
+    get path() { return this._path; }
+    get ref() {
+        if (!this._ref)
+            throw new Error('Database reference is not available.');
+        return this._ref;
+    }
+    // ── Initialization ────────────────────────────────────────────────────────
+    _init() {
+        if (typeof window === 'undefined') {
+            this._loading = false;
+            return;
+        }
         try {
-            const database = firebaseService.getDatabaseInstance();
-            if (!database) {
-                throw new Error('Database instance not available');
-            }
-            this.dbRef = ref(database, path);
-            this.unsubscribe = onValue(this.dbRef, (snapshot) => {
-                this._data = snapshot.val();
-                this._loading = false;
+            const db = getDb();
+            this._ref = ref(db, this._path);
+            this._unsubscribe = onValue(this._ref, (snap) => {
+                this._data = snap.val();
                 this._error = null;
-            }, (error) => {
-                this._error = error;
+                this._loading = false;
+            }, (err) => {
+                this._error = err;
                 this._loading = false;
             });
         }
-        catch (error) {
-            this._error = error;
+        catch (err) {
+            this._error = err instanceof Error ? err : new Error(String(err));
             this._loading = false;
         }
     }
-    /**
-     * Pushes new data to list
-     * @param {T} data Data to push
-     * @returns {Promise<string | null>} New item key or null if failed
-     *
-     * @example
-     * ```typescript
-     * const key = await chatRef.push({
-     *   text: 'Hello',
-     *   userId: '123',
-     *   timestamp: Date.now()
-     * });
-     * ```
-     */
+    // ── Write operations ──────────────────────────────────────────────────────
+    /** Pushes a new child node (list append). Returns the new key, or null on failure. */
     async push(data) {
-        if (!this.dbRef)
+        if (!this._ref)
             return null;
-        const newRef = push(this.dbRef);
+        const newRef = push(this._ref);
         await set(newRef, data);
         return newRef.key;
     }
-    /**
-     * Sets data at reference
-     * @param {T} data Data to set
-     *
-     * @example
-     * ```typescript
-     * await chatRef.set({
-     *   text: 'Updated message',
-     *   userId: '123',
-     *   timestamp: Date.now()
-     * });
-     * ```
-     */
+    /** Overwrites the node with new data. */
     async set(data) {
-        if (!this.dbRef)
+        if (!this._ref)
             return;
-        await set(this.dbRef, data);
+        await set(this._ref, data);
     }
-    /**
-     * Updates data at reference
-     * @param {Partial<T>} data Data to update
-     *
-     * @example
-     * ```typescript
-     * await chatRef.update({
-     *   text: 'Edited message'
-     * });
-     * ```
-     */
+    /** Merges partial data into the node (shallow merge). */
     async update(data) {
-        if (!this.dbRef)
+        if (!this._ref)
             return;
-        await update(this.dbRef, data);
+        await update(this._ref, data);
     }
-    /**
-     * Removes data at reference
-     *
-     * @example
-     * ```typescript
-     * await chatRef.remove();
-     * ```
-     */
+    /** Deletes the node. */
     async remove() {
-        if (!this.dbRef)
+        if (!this._ref)
             return;
-        await remove(this.dbRef);
-    }
-    /** Gets current data */
-    get data() {
-        return this._data;
+        await remove(this._ref);
     }
-    /** Gets loading state */
-    get loading() {
-        return this._loading;
-    }
-    /** Gets error state */
-    get error() {
-        return this._error;
-    }
-    /**
-     * Gets database reference
-     * @throws {Error} If reference is not available
-     */
-    get ref() {
-        if (!this.dbRef) {
-            throw new Error('Database reference is not available');
-        }
-        return this.dbRef;
+    /** One-time fetch of current data (no subscription). */
+    async fetchOnce() {
+        if (!this._ref)
+            return null;
+        const snap = await get(this._ref);
+        return snap.val();
     }
-    /** Cleanup subscription */
+    /** Stops the real-time listener. */
     dispose() {
-        if (this.unsubscribe) {
-            this.unsubscribe();
-            this.unsubscribe = null;
-        }
+        this._unsubscribe?.();
+        this._unsubscribe = null;
     }
 }
 /**
- * Creates a reactive Realtime Database reference
- * @template T Data type
- * @param {string} path Database path
- * @param {T} [startWith] Initial data
- * @returns {FirekitRealtimeDB<T>} Database subscription instance
+ * Reactive RTDB list — subscribes to a node and exposes its children as
+ * a typed array with each item's key injected as `id`.
  *
  * @example
- * ```typescript
- * const chatRef = firekitRealtimeDB<ChatMessage>('chats/123');
+ * ```svelte
+ * <script lang="ts">
+ *   import { firekitNodeList } from 'svelte-firekit';
+ *   const messages = firekitNodeList<Message>('rooms/123/messages');
+ * </script>
+ * {#each messages.list as msg}
+ *   <p>{msg.id}: {msg.text}</p>
+ * {/each}
  * ```
  */
-export function firekitRealtimeDB(path, startWith) {
-    return new FirekitRealtimeDB(path, startWith);
+export class FirekitNodeList extends FirekitNode {
+    list = $derived(this.data
+        ? Object.entries(this.data).map(([key, value]) => ({
+            id: key,
+            ...value
+        }))
+        : []);
 }
+// ── Field value helpers ───────────────────────────────────────────────────────
+/** RTDB server timestamp sentinel. */
+export const rtdbServerTimestamp = serverTimestamp;
+/** RTDB increment sentinel. */
+export const rtdbIncrement = increment;
+// ── Factory functions ─────────────────────────────────────────────────────────
 /**
- * Creates a reactive Realtime Database list reference
- * Automatically converts data to array format with IDs
- *
- * @template T List item type
- * @param {string} path Database path
- * @param {T[]} [startWith=[]] Initial array data
- * @returns {FirekitRealtimeDB} Database subscription instance with array support
- *
- * @example
- * ```typescript
- * const messagesList = firekitRealtimeList<ChatMessage>('messages');
- * console.log(messagesList.list); // Array of messages with IDs
- * ```
+ * Creates a reactive RTDB node subscription.
  */
-export function firekitRealtimeList(path, startWith = []) {
-    const startWithRecord = startWith.reduce((acc, item, index) => {
-        acc[`key${index}`] = item;
-        return acc;
-    }, {});
-    return new (class extends FirekitRealtimeDB {
-        _list = $derived(this.data
-            ? Object.entries(this.data).map(([key, value]) => ({
-                id: key,
-                ...value
-            }))
-            : []);
-        get list() {
-            return this._list;
-        }
-    })(path, startWithRecord);
+export function firekitNode(path, startWith) {
+    return new FirekitNode(path, startWith);
+}
+/**
+ * Creates a reactive RTDB node subscription that exposes children as an array.
+ */
+export function firekitNodeList(path, startWith) {
+    let startRecord;
+    if (startWith) {
+        startRecord = Object.fromEntries(startWith.map((item, i) => [`__init_${i}`, item]));
+    }
+    return new FirekitNodeList(path, startRecord);
 }

package/dist/services/remote-config.svelte.d.ts

@@ -0,0 +1,73 @@
+import { type Value } from 'firebase/remote-config';
+/**
+ * Reactive Firebase Remote Config service.
+ *
+ * Fetches and activates remote configuration values, exposes them reactively,
+ * and optionally subscribes to real-time config updates.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { firekitRemoteConfig } from 'svelte-firekit';
+ *
+ *   const rc = firekitRemoteConfig({
+ *     defaults: { welcomeMessage: 'Hello!', featureEnabled: false },
+ *     minimumFetchIntervalMs: 3600_000
+ *   });
+ *   await rc.fetchAndActivate();
+ * </script>
+ * <p>{rc.getString('welcomeMessage')}</p>
+ * ```
+ */
+export declare class FirekitRemoteConfig {
+    private _loading;
+    private _error;
+    private _lastFetchTime;
+    private _activated;
+    /** Bumped whenever config is activated, so derived reads stay reactive. */
+    private _version;
+    private _rc;
+    private _unsubscribe;
+    private _options;
+    constructor(options?: FirekitRemoteConfigOptions);
+    get loading(): boolean;
+    get error(): Error | null;
+    get activated(): boolean;
+    get lastFetchTime(): Date | null;
+    private _init;
+    private _subscribeToUpdates;
+    /** Fetches fresh config from the server and activates it. */
+    fetchAndActivate(): Promise<boolean>;
+    /** Fetches config without activating. */
+    fetch(): Promise<void>;
+    /** Activates the last fetched config. */
+    activate(): Promise<boolean>;
+    /** Returns a string config value. Uses default if not set. */
+    getString(key: string, defaultValue?: string): string;
+    /** Returns a boolean config value. */
+    getBoolean(key: string, defaultValue?: boolean): boolean;
+    /** Returns a number config value. */
+    getNumber(key: string, defaultValue?: number): number;
+    /** Returns the raw Value object for a key. */
+    getValue(key: string): Value | null;
+    /** Returns all config key-value pairs as a plain object. */
+    getAll(): Record<string, Value>;
+    /** Stops the real-time config update listener. */
+    dispose(): void;
+}
+export interface FirekitRemoteConfigOptions {
+    /** Default values applied before remote values are fetched. */
+    defaults?: Record<string, string | number | boolean>;
+    /** Minimum interval between fetches in ms. Default: 43200000 (12h). */
+    minimumFetchIntervalMs?: number;
+    /** Fetch timeout in ms. Default: 60000 (60s). */
+    fetchTimeoutMs?: number;
+    /** Automatically fetch + activate on init. Default: true. */
+    autoFetch?: boolean;
+    /** Subscribe to real-time config updates. Default: false. */
+    realtime?: boolean;
+    /** SDK log level. */
+    logLevel?: 'debug' | 'error' | 'silent';
+}
+/** Creates a reactive Remote Config instance. */
+export declare function firekitRemoteConfig(options?: FirekitRemoteConfigOptions): FirekitRemoteConfig;