@littoral/literally-firebase 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.2.0](https://github.com/Zoramite/literally/compare/literally-firebase-v0.1.0...literally-firebase-v0.2.0) (2026-06-23)
+
+
+### Features
+
+* Firestore watcher mixin and interface for firestore converter ([c51b2d2](https://github.com/Zoramite/literally/commit/c51b2d25a1f50ebd525b1d3a7222755e65a6f430))

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@littoral/literally-firebase",
+  "version": "0.2.0",
+  "description": "Firebase utilities and integration for littoral components.",
+  "exports": {
+    "./*": "./src/*.ts"
+  },
+  "keywords": [
+    "lit",
+    "firebase"
+  ],
+  "homepage": "https://github.com/Zoramite/literally#readme",
+  "bugs": {
+    "url": "https://github.com/Zoramite/literally/issues"
+  },
+  "license": "MIT",
+  "author": "Randy Merrill <Zoramite+github@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zoramite/literally.git"
+  },
+  "dependencies": {},
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@littoral/literally": "^2.5.0",
+    "lit": "^3.3.3",
+    "firebase": "^12.14.0"
+  }
+}

package/src/firestore/converter.ts

@@ -0,0 +1,35 @@
+import {
+  QueryDocumentSnapshot,
+  type SnapshotOptions,
+} from 'firebase/firestore';
+
+/**
+ * Interface representing a Firestore data converter.
+ * Compatible with the custom object converter pattern expected by Firebase Firestore's `withConverter`.
+ *
+ * This allows you to write type-safe queries and database operations using strongly typed model classes/interfaces
+ * instead of raw Firestore DocumentData.
+ *
+ * @template Type The type representing the domain model class or interface.
+ */
+export interface FBConverter<Type> {
+  /**
+   * Converts a domain model object of type `Type` into a plain object suitable for saving to Firestore.
+   *
+   * @param data The domain model instance to serialize.
+   * @returns A plain object suitable for writing to Firestore.
+   */
+  toFirestore: (data: Type) => any;
+
+  /**
+   * Converts a Firestore snapshot back into a strongly typed domain model object of type `Type`.
+   *
+   * @param snap The query document snapshot from Firestore.
+   * @param options Snapshot conversion options provided by the Firestore SDK.
+   * @returns The deserialized domain model instance.
+   */
+  fromFirestore: (
+    snap: QueryDocumentSnapshot,
+    options: SnapshotOptions,
+  ) => Type;
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Main entry point for the `@littoral/literally-firebase` package.
+ * Exports Firestore utilities and Lit element mixins for integration.
+ */
+
+export { type FBConverter } from './firestore/converter';
+
+export {
+  FirestoreListenerMixin,
+  type FirestoreListenerMixinInterface,
+} from './mixins/firestore-watchers.mixin';

package/src/mixins/firestore-watchers.mixin.test.ts

@@ -0,0 +1,58 @@
+// @vitest-environment jsdom
+import { fixture, defineCE } from '@open-wc/testing';
+import { LitElement } from 'lit';
+import { describe, test, expect, vi } from 'vitest';
+
+import { FirestoreListenerMixin } from './firestore-watchers.mixin';
+
+const TestTag = defineCE(class extends FirestoreListenerMixin(LitElement) {});
+
+describe('FirestoreListenerMixin', () => {
+  test('adds and stops watchers', async () => {
+    const el = await fixture<any>(`<${TestTag}></${TestTag}>`);
+    const unsubscribe = vi.fn();
+
+    el.addFirebaseWatcher('test', unsubscribe);
+    expect(el.hasFirebaseWatcher('test')).toBe(true);
+
+    el.stopFirebaseWatcher('test');
+    expect(unsubscribe).toHaveBeenCalled();
+    expect(el.hasFirebaseWatcher('test')).toBe(false);
+  });
+
+  test('replaces existing watcher with same name', async () => {
+    const el = await fixture<any>(`<${TestTag}></${TestTag}>`);
+    const unsubscribe1 = vi.fn();
+    const unsubscribe2 = vi.fn();
+
+    el.addFirebaseWatcher('test', unsubscribe1);
+    el.addFirebaseWatcher('test', unsubscribe2);
+
+    expect(unsubscribe1).toHaveBeenCalled();
+    expect(el.hasFirebaseWatcher('test')).toBe(true);
+  });
+
+  test('stops all watchers on disconnect', async () => {
+    const el = await fixture<any>(`<${TestTag}></${TestTag}>`);
+    const unsubscribe1 = vi.fn();
+    const unsubscribe2 = vi.fn();
+
+    el.addFirebaseWatcher('one', unsubscribe1);
+    el.addFirebaseWatcher('two', unsubscribe2);
+
+    // Disconnect the element
+    el.remove();
+    // Wait for disconnectedCallback (it's synchronous but let's be safe)
+
+    expect(unsubscribe1).toHaveBeenCalled();
+    expect(unsubscribe2).toHaveBeenCalled();
+    expect(el.hasFirebaseWatcher('one')).toBe(false);
+    expect(el.hasFirebaseWatcher('two')).toBe(false);
+  });
+
+  test('handles undefined watcher in addFirebaseWatcher', async () => {
+    const el = await fixture<any>(`<${TestTag}></${TestTag}>`);
+    el.addFirebaseWatcher('test', undefined);
+    expect(el.hasFirebaseWatcher('test')).toBe(false);
+  });
+});

package/src/mixins/firestore-watchers.mixin.ts

@@ -0,0 +1,135 @@
+import { type Constructor } from '@littoral/literally/mixins/mixin';
+import { type Unsubscribe } from 'firebase/firestore';
+import { LitElement } from 'lit';
+
+/**
+ * Interface representing the API provided by `FirestoreListenerMixin`.
+ * Provides utilities to cleanly manage active Firestore live listeners (subscriptions)
+ * and ensure they are cleaned up when elements disconnect.
+ */
+export interface FirestoreListenerMixinInterface {
+  /**
+   * Registers a active Firebase listener unsubscribe callback under a given name.
+   * If a watcher with the same name already exists, it is unsubscribed first before
+   * the new one is stored.
+   *
+   * @param name Unique name to identify the listener.
+   * @param watcher The unsubscribe callback returned by the Firestore listener configuration.
+   */
+  addFirebaseWatcher(name: string, watcher: Unsubscribe | undefined): void;
+
+  /**
+   * Checks whether a Firebase listener with the given name is currently active and registered.
+   *
+   * @param name Unique name of the listener.
+   * @returns True if the listener is active, false otherwise.
+   */
+  hasFirebaseWatcher(name: string): boolean;
+
+  /**
+   * Unsubscribes and stops a specific active listener by its unique name, removing it from the registry.
+   *
+   * @param name Unique name of the listener.
+   */
+  stopFirebaseWatcher(name: string): void;
+
+  /**
+   * Unsubscribes and stops all active listeners currently tracked by the mixin.
+   */
+  clearFirebaseWatchers(): void;
+}
+
+/**
+ * A LitElement mixin that simplifies managing Firestore reactive watch listeners.
+ *
+ * Automatically tracks unsubscribe functions returned by Firestore listener configuration
+ * (e.g. `onSnapshot`) and automatically cleans them up (unsubscribes) during the element's
+ * `disconnectedCallback` lifecycle hook to prevent memory leaks.
+ *
+ * @example
+ * ```ts
+ * class MyElement extends FirestoreListenerMixin(LitElement) {
+ *   connectedCallback() {
+ *     super.connectedCallback();
+ *     const unsubscribe = onSnapshot(docRef, (doc) => { ... });
+ *     this.addFirebaseWatcher('my-doc-watcher', unsubscribe);
+ *   }
+ * }
+ * ```
+ */
+export const FirestoreListenerMixin = <T extends Constructor<LitElement>>(
+  superClass: T,
+) => {
+  class FirestoreListenerMixinElement
+    extends superClass
+    implements FirestoreListenerMixinInterface
+  {
+    static styles = [(superClass as unknown as typeof LitElement).styles ?? []];
+
+    /**
+     * Map tracking active Firestore unsubscribe callbacks by their registry key name.
+     */
+    protected firebaseWatchers: Record<string, Unsubscribe> = {};
+
+    /**
+     * Standard Web Component lifecycle hook.
+     * Invoked when the component is disconnected from the DOM.
+     * Automatically triggers cleanup of all registered Firebase listeners.
+     */
+    disconnectedCallback() {
+      this.clearFirebaseWatchers();
+      super.disconnectedCallback();
+    }
+
+    /**
+     * Iterates over all active registered Firebase watchers, calls their unsubscribe callbacks
+     * to terminate connection stream, and removes them from registry.
+     */
+    clearFirebaseWatchers() {
+      for (const key of Object.keys(this.firebaseWatchers)) {
+        this.firebaseWatchers[key]();
+        delete this.firebaseWatchers[key];
+      }
+    }
+
+    /**
+     * Registers a new Firebase watcher unsubscribe callback under a given name.
+     * Ensures any previous watcher with the same name is cleanly terminated first.
+     *
+     * @param name Unique key for tracking this listener.
+     * @param watcher Unsubscribe callback returned by Firestore stream setups.
+     */
+    addFirebaseWatcher(name: string, watcher: Unsubscribe | undefined) {
+      // Stop any existing watchers with the same name.
+      this.firebaseWatchers[name]?.();
+
+      if (!watcher) {
+        return;
+      }
+
+      this.firebaseWatchers[name] = watcher;
+    }
+
+    /**
+     * Queries the registry to see if an active watcher is registered.
+     *
+     * @param name Unique key of the listener.
+     * @returns Boolean indicating presence of active listener.
+     */
+    hasFirebaseWatcher(name: string): boolean {
+      return Boolean(this.firebaseWatchers[name]);
+    }
+
+    /**
+     * Unsubscribes from a specific active watcher and deletes its registry key.
+     *
+     * @param name Unique key of the listener to stop.
+     */
+    stopFirebaseWatcher(name: string) {
+      this.firebaseWatchers[name]?.();
+      delete this.firebaseWatchers[name];
+    }
+  }
+  return FirestoreListenerMixinElement as Constructor<FirestoreListenerMixinInterface> &
+    T;
+};

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"],
+  "references": [{ "path": "../literally" }]
+}