ngx-firestore-wrapper-kit 0.0.1 → 0.0.3

package/README.md

@@ -1,63 +1,243 @@
-# NgxFirestoreKit
+# ngx-firestore-wrapper-kit — Integration Guide
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 20.3.0.
+Steps to install, configure, and use this library in an Angular application.
 
-## Code scaffolding
+<p style="font-size: 1.15rem; line-height: 1.6;"><strong>Requirements:</strong> Angular ^20.3.0, a Firebase project with Firestore enabled.</p>
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+<div style="background: #f6f8fa; border: 1px solid #d0d7de; border-left: 4px solid #0969da; border-radius: 8px; padding: 1rem 1.25rem; margin: 1rem 0; font-size: 1rem; line-height: 1.6;">
+
+<p style="font-size: 1.05rem; font-weight: 600; margin: 0 0 0.75rem; padding-bottom: 0.5rem; border-bottom: 1px solid #d8dee4;">On this page</p>
+
+<ul style="margin: 0; padding-left: 1.25rem;">
+  <li style="margin-bottom: 0.35rem;"><a href="#1-install" style="color: #0969da; text-decoration: none;">1. Install</a></li>
+  <li style="margin-bottom: 0.35rem;"><a href="#2-firebase-configuration" style="color: #0969da; text-decoration: none;">2. Firebase configuration</a></li>
+  <li style="margin-bottom: 0.35rem;"><a href="#3-register-the-library-in-your-app" style="color: #0969da; text-decoration: none;">3. Register the library in your app</a></li>
+  <li style="margin-bottom: 0.35rem;"><a href="#4-usage" style="color: #0969da; text-decoration: none;">4. Usage</a></li>
+  <li style="margin-bottom: 0.35rem;"><a href="#5-checklist" style="color: #0969da; text-decoration: none;">5. Checklist</a></li>
+  <li style="margin-bottom: 0.35rem;"><a href="#exports-reference" style="color: #0969da; text-decoration: none;">Exports reference</a></li>
+</ul>
+
+<p style="font-size: 0.95rem; font-weight: 600; margin: 1rem 0 0.5rem; color: #57606a;">Usage sections</p>
+
+<ul style="margin: 0; padding-left: 1.25rem;">
+  <li style="margin-bottom: 0.35rem;"><a href="#response-shape" style="color: #0969da; text-decoration: none;">Response shape</a></li>
+  <li style="margin-bottom: 0.35rem;"><a href="#listen-to-a-document-real-time" style="color: #0969da; text-decoration: none;">Listen to a document (real-time)</a></li>
+  <li style="margin-bottom: 0.35rem;"><a href="#listen-to-a-collection-real-time" style="color: #0969da; text-decoration: none;">Listen to a collection (real-time)</a></li>
+  <li style="margin-bottom: 0.35rem;"><a href="#path-helpers" style="color: #0969da; text-decoration: none;">Path helpers</a></li>
+</ul>
+
+</div>
+
+---
+
+<a id="1-install"></a>
+
+## 1. Install
+
+### From npm
 
 ```bash
-ng generate component component-name
+npm install ngx-firestore-wrapper-kit
 ```
 
-For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
+---
 
-```bash
-ng generate --help
+<a id="2-firebase-configuration"></a>
+
+## 2. Firebase configuration
+
+Add the Firebase config to your environment file (`src/environments/environment.ts`):
+
+```typescript
+import { FirebaseOptions } from '@angular/fire/app';
+
+export const environment = {
+  production: false,
+  firebaseConfig: {
+    apiKey: 'YOUR_API_KEY',
+    authDomain: 'YOUR_PROJECT.firebaseapp.com',
+    projectId: 'YOUR_PROJECT_ID',
+    storageBucket: 'YOUR_PROJECT.appspot.com',
+    messagingSenderId: 'YOUR_SENDER_ID',
+    appId: 'YOUR_APP_ID'
+  } as FirebaseOptions
+};
 ```
 
-## Building
+Get these values from [Firebase Console](https://console.firebase.google.com/) → **Project settings** → **Your apps** → Web app config.
 
-To build the library, run:
+---
 
-```bash
-ng build ngx-firestore-kit
+<a id="3-register-the-library-in-your-app"></a>
+
+## 3. Register the library in your app
+
+**`app.config.ts`:**
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { provideFirestoreKit } from 'ngx-firestore-wrapper-kit';
+import { environment } from './environments/environment';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideFirestoreKit(environment.firebaseConfig)
+  ]
+};
 ```
 
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
+---
 
-### Publishing the Library
+<a id="4-usage"></a>
 
-Once the project is built, you can publish your library by following these steps:
+## 4. Usage
 
-1. Navigate to the `dist` directory:
-   ```bash
-   cd dist/ngx-firestore-kit
-   ```
+Import from the package:
 
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
+```typescript
+import {
+  FirestoreDataService,
+  FirestorePaths,
+  FirestoreResponse
+} from 'ngx-firestore-wrapper-kit';
+```
 
-## Running unit tests
+Inject `FirestoreDataService` where you need Firestore data. It is `providedIn: 'root'`, so no extra providers are required.
 
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+<a id="response-shape"></a>
 
-```bash
-ng test
+### Response shape
+
+All listener methods return `Observable<FirestoreResponse<T>>`:
+
+```typescript
+interface FirestoreResponse<T> {
+  success: boolean;
+  data: any;      // payload when success is true
+  error: unknown; // error when success is false
+}
 ```
 
-## Running end-to-end tests
+Always check `success` before using `data`.
 
-For end-to-end (e2e) testing, run:
+---
 
-```bash
-ng e2e
+<a id="listen-to-a-document-real-time"></a>
+
+### Listen to a document (real-time)
+
+```typescript
+import { inject, OnDestroy, OnInit } from '@angular/core';
+import { Subscription } from 'rxjs';
+import { FirestoreDataService, FirestorePaths, FirestoreResponse } from 'ngx-firestore-wrapper-kit';
+
+interface BatchJob {
+  status: string;
+  progress: number;
+}
+
+export class BatchJobComponent implements OnInit, OnDestroy {
+  private readonly firestoreData = inject(FirestoreDataService);
+  private sub?: Subscription;
+
+  response: FirestoreResponse<BatchJob> | null = null;
+
+  ngOnInit(): void {
+    const path = FirestorePaths.getBatchJobDocumentPath('client-001', 'job-001');
+
+    this.sub = this.firestoreData
+      .listenToDocument<BatchJob>(path)
+      .subscribe((res) => (this.response = res));
+  }
+
+  ngOnDestroy(): void {
+    this.sub?.unsubscribe();
+  }
+}
 ```
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+---
+
+<a id="listen-to-a-collection-real-time"></a>
+
+### Listen to a collection (real-time)
+
+```typescript
+import { inject, OnDestroy, OnInit } from '@angular/core';
+import { Subscription } from 'rxjs';
+import { FirestoreDataService, FirestorePaths, FirestoreResponse } from 'ngx-firestore-wrapper-kit';
+
+interface BatchJob {
+  status: string;
+  progress: number;
+}
+
+export class BatchJobListComponent implements OnInit, OnDestroy {
+  private readonly firestoreData = inject(FirestoreDataService);
+  private sub?: Subscription;
+
+  response: FirestoreResponse<BatchJob[]> | null = null;
+
+  ngOnInit(): void {
+    const path = FirestorePaths.getBatchJobCollectionPath('client-001');
+
+    this.sub = this.firestoreData
+      .listenToCollection<BatchJob>(path)
+      .subscribe((res) => (this.response = res));
+  }
+
+  ngOnDestroy(): void {
+    this.sub?.unsubscribe();
+  }
+}
+```
+
+---
+
+<a id="path-helpers"></a>
+
+### Path helpers
+
+Build paths as **string arrays** — alternating collection and document IDs:
+
+```typescript
+// Document: collection/{collectionId}/childCollection/{childCollectionDocumentId}
+const documentPath = ['collection', 'collection-001', 'childCollection', 'child-collection-001'];
+
+// Collection: collection/{collectionId}/childCollection
+const collectionPath = ['collection', 'collection-001', 'childCollection'];
+```
+
+**Example with the service:**
+
+```typescript
+this.firestoreData
+  .listenToDocument<ChildDocument>(documentPath)
+  .subscribe((res) => { /* ... */ });
+```
+
+---
+
+<a id="5-checklist"></a>
+
+## 5. Checklist
+
+- [ ] `ngx-firestore-wrapper-kit` installed
+- [ ] Firebase config added to `environment.ts`
+- [ ] `provideFirestoreKit(environment.firebaseConfig)` in root providers
+- [ ] `FirestoreDataService` injected in components/services
+- [ ] Paths passed as `string[]`
+- [ ] Subscriptions unsubscribed in `ngOnDestroy` (or use `async` pipe)
+
+---
+
+<a id="exports-reference"></a>
 
-## Additional Resources
+## Exports reference
 
-For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
+| Export | Use |
+|--------|-----|
+| `provideFirestoreKit(config)` | Bootstrap Firebase + Firestore in the app |
+| `FirestoreDataService` | `listenToDocument()`, `listenToCollection()` |
+| `FirestorePaths` | Static path segment helpers |
+| `FirestoreResponse<T>` | Type for listener responses |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-firestore-wrapper-kit",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "peerDependencies": {
     "@angular/common": "^20.3.0",
     "@angular/core": "^20.3.0"