ngx-firestore-wrapper-kit 0.0.1 → 0.0.2

package/README.md

@@ -1,63 +1,346 @@
-# NgxFirestoreKit
+# ngx-firestore-wrapper-kit — Integration Guide
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 20.3.0.
+<style>
+  .guide-header {
+    max-width: 960px;
+    margin: 0 auto 1.5rem;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    line-height: 1.6;
+    color: #24292f;
+  }
 
-## Code scaffolding
+  .guide-intro {
+    margin: 0 0 1rem;
+    color: #57606a;
+  }
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+  .guide-requirements {
+    background: #fff8e6;
+    border-left: 4px solid #d4a72c;
+    border-radius: 0 6px 6px 0;
+    padding: 0.75rem 1rem;
+    margin: 0 0 1.25rem;
+    font-size: 0.95rem;
+  }
+
+  .guide-nav {
+    background: #f6f8fa;
+    border: 1px solid #d0d7de;
+    border-left: 4px solid #0969da;
+    border-radius: 8px;
+    padding: 1rem 1.25rem;
+    margin: 0 0 1.5rem;
+  }
+
+  .guide-nav-title {
+    margin: 0 0 0.85rem;
+    padding-bottom: 0.65rem;
+    border-bottom: 1px solid #d8dee4;
+    font-size: 0.95rem;
+    font-weight: 600;
+    color: #24292f;
+  }
+
+  .guide-nav-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+    gap: 0.25rem 1rem;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .guide-nav-grid li {
+    margin: 0;
+  }
+
+  .guide-nav-grid a {
+    display: block;
+    padding: 0.4rem 0.5rem;
+    color: #0969da;
+    text-decoration: none;
+    font-size: 0.9rem;
+    border-radius: 4px;
+    transition: background 0.15s ease, color 0.15s ease;
+  }
+
+  .guide-nav-grid a:hover {
+    color: #0550ae;
+    background: #eef6ff;
+  }
+
+  .guide-nav-sub {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+    gap: 0.2rem 1rem;
+    margin: 0.75rem 0 0;
+    padding: 0.75rem 0 0;
+    border-top: 1px solid #d8dee4;
+    list-style: none;
+  }
+
+  .guide-nav-sub li {
+    margin: 0;
+  }
+
+  .guide-nav-sub a {
+    display: block;
+    padding: 0.35rem 0.5rem;
+    font-size: 0.85rem;
+    color: #57606a;
+    text-decoration: none;
+    border-radius: 4px;
+    transition: background 0.15s ease, color 0.15s ease;
+  }
+
+  .guide-nav-sub a:hover {
+    color: #0969da;
+    background: #eef6ff;
+  }
+
+  .guide-section {
+    scroll-margin-top: 1.5rem;
+  }
+</style>
+
+<div class="guide-header">
+
+<p class="guide-intro">Steps to install, configure, and use this library in an Angular application.</p>
+
+<div class="guide-requirements">
+  <strong>Requirements:</strong> Angular ^20.3.0, a Firebase project with Firestore enabled.
+</div>
+
+<nav class="guide-nav" aria-label="Table of contents">
+  <p class="guide-nav-title">On this page</p>
+  <ul class="guide-nav-grid">
+    <li><a href="#install">1. Install</a></li>
+    <li><a href="#firebase-configuration">2. Firebase configuration</a></li>
+    <li><a href="#register-the-library">3. Register the library</a></li>
+    <li><a href="#usage">4. Usage</a></li>
+    <li><a href="#checklist">5. Checklist</a></li>
+    <li><a href="#exports-reference">Exports reference</a></li>
+  </ul>
+  <ul class="guide-nav-sub">
+    <li><a href="#response-shape">↳ Response shape</a></li>
+    <li><a href="#listen-to-a-document">↳ Listen to a document</a></li>
+    <li><a href="#listen-to-a-collection">↳ Listen to a collection</a></li>
+    <li><a href="#path-helpers">↳ Path helpers</a></li>
+  </ul>
+</nav>
+
+</div>
+
+---
+
+<a id="install" class="guide-section"></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="firebase-configuration" class="guide-section"></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="register-the-library" class="guide-section"></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.
+---
+
+<a id="usage" class="guide-section"></a>
 
-### Publishing the Library
+## 4. Usage
 
-Once the project is built, you can publish your library by following these steps:
+Import from the package:
 
-1. Navigate to the `dist` directory:
-   ```bash
-   cd dist/ngx-firestore-kit
-   ```
+```typescript
+import {
+  FirestoreDataService,
+  FirestorePaths,
+  FirestoreResponse
+} from 'ngx-firestore-wrapper-kit';
+```
 
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
+Inject `FirestoreDataService` where you need Firestore data. It is `providedIn: 'root'`, so no extra providers are required.
 
-## Running unit tests
+<a id="response-shape" class="guide-section"></a>
 
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+### Response shape
 
-```bash
-ng test
+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" class="guide-section"></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();
+  }
+}
+```
+
+---
+
+<a id="listen-to-a-collection" class="guide-section"></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" class="guide-section"></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'];
 ```
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+**Example with the service:**
+
+```typescript
+this.firestoreData
+  .listenToDocument<ChildDocument>(documentPath)
+  .subscribe((res) => { /* ... */ });
+```
+
+---
+
+<a id="checklist" class="guide-section"></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" class="guide-section"></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.2",
   "peerDependencies": {
     "@angular/common": "^20.3.0",
     "@angular/core": "^20.3.0"