edmaxlabs-core 2.5.6 → 2.6.7

package/README.md

@@ -3,302 +3,445 @@
 [![npm version](https://badge.fury.io/js/edmaxlabs-core.svg)](https://badge.fury.io/js/edmaxlabs-core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-`edmaxlabs-core` is the official SDK for EdmaxLabs services, providing seamless integration with Authentication, Database, Storage, and Cloud Functions. **Framework agnostic** - works with any JavaScript framework or vanilla JS.
+`edmaxlabs-core` is the official framework-agnostic SDK for EdmaxLabs services. It supports database access, realtime listeners, offline persistence, authentication, storage, and cloud functions.
 
-## 🚀 Features
-
-- **Authentication** - Secure user authentication
-- **Database** - Real-time database with offline support
-- **Storage** - File upload/download
-- **Cloud Functions** - Serverless function execution
-- **Framework Agnostic** - Works with React, Vue, Angular, vanilla JS, Node.js
-- **Offline Support** - Automatic sync when online
-- **TypeScript** - Full TypeScript support
-
-## 📦 Installation
+## Installation
 
 ```bash
 npm install edmaxlabs-core
 ```
 
-## 🧠 Quick Start
-
-### Basic Usage
+## Create an App
 
-```typescript
+```ts
 import EdmaxLabs from "edmaxlabs-core";
 
 const app = new EdmaxLabs({
   token: "your-api-token",
   project: "your-project-id",
-  persistence: true, // Enable offline persistence
+  persistence: true,
+  app_name: "my-web-app",
 });
-
-// Get data
-const messages = await app.getDatabase.collection("messages").get();
-console.log(messages);
 ```
 
-### React Integration (Recommended)
+Config options:
+
+- `token`: required API token
+- `project`: required project id
+- `persistence`: enable offline persistence and sync
+- `app_name`: optional cache namespace for the local persistence layer
+- `default_bucket`: optional default storage bucket
+
+## React Quick Start
 
 ```tsx
+import { useEffect, useState } from "react";
 import EdmaxLabs from "edmaxlabs-core";
 
 const app = new EdmaxLabs({
-  token: "your-token",
+  token: "your-api-token",
   project: "your-project-id",
   persistence: true,
+  app_name: "chat-app",
 });
 
-function ChatApp() {
-  const [messages, setMessages] = useState([]);
+export function MessagesList() {
+  const [messages, setMessages] = useState<any[]>([]);
   const [loading, setLoading] = useState(true);
 
   useEffect(() => {
-    const unsubscribe = app.getDatabase.collection("messages").onSnapshot(
-      (docs) => {
-        setMessages(docs.map(doc => doc.data()));
+    const unsubscribe = app.getDatabase
+      .collection("messages")
+      .onSnapshot((snapshots) => {
+        setMessages(snapshots.map((doc) => doc.data));
         setLoading(false);
-      }
-    );
-    return unsubscribe; // Important: cleanup to prevent memory leaks
+      });
+
+    return unsubscribe;
   }, []);
 
-  if (loading) return <div>Loading...</div>;
+  if (loading) return <p>Loading...</p>;
 
   return (
-    <div>
-      {messages.map(msg => (
-        <div key={msg.id}>{msg.text}</div>
+    <ul>
+      {messages.map((message) => (
+        <li key={message.id}>{message.text}</li>
       ))}
-    </div>
+    </ul>
   );
 }
 ```
-    <div>
-      {messages.map(msg => (
-        <div key={msg.id}>{msg.text}</div>
-      ))}
-    </div>
-  );
-}
+
+## Realtime
+
+### `onSnapshot`
+
+`onSnapshot` is still fully supported. For collections and queries it returns the full current result set every time something changes.
+
+```ts
+const unsubscribe = app.getDatabase
+  .collection("messages")
+  .onSnapshot((snapshots, change, changedDocId) => {
+    console.log("change:", change);
+    console.log("changedDocId:", changedDocId);
+    console.log("docs:", snapshots.map((doc) => doc.data));
+  });
+
+unsubscribe();
 ```
 
-## 🔧 Configuration
+Document listeners work the same way:
 
-```typescript
-const app = new EdmaxLabs({
-  token: "your-api-token",           // Required: Your API token
-  project: "your-project-id",        // Required: Project identifier
-  baseUrl: "https://api.edmaxlabs.com", // Optional: API endpoint
-  persistence: true,               // Optional: Enable offline persistence
-  appName: "my-app",                 // Optional: Unique app identifier
-});
+```ts
+const unsubscribe = app.getDatabase
+  .collection("messages")
+  .doc("message-1")
+  .onSnapshot((snapshot, change) => {
+    console.log("change:", change);
+    console.log("doc:", snapshot?.data ?? null);
+  });
+```
+
+### `onChildListener`
+
+Yes, `onChildListener` is now available.
+
+Use it when you want Firestore-style granular callbacks instead of diffing the full array yourself.
+
+```ts
+const unsubscribe = app.getDatabase
+  .collection("messages")
+  .onChildListener({
+    onChildAdded(snapshot, context) {
+      console.log("added:", snapshot.data);
+      console.log("index:", context.newIndex);
+      console.log("fromCache:", context.fromCache);
+    },
+    onChildUpdated(snapshot, context) {
+      console.log("updated:", snapshot.data);
+      console.log("oldIndex:", context.oldIndex);
+      console.log("newIndex:", context.newIndex);
+      console.log("previous:", context.previousDoc?.data ?? null);
+    },
+    onChildRemoved(snapshot, context) {
+      console.log("removed:", snapshot.data);
+      console.log("oldIndex:", context.oldIndex);
+    },
+  });
+
+unsubscribe();
+```
+
+It also works on queries:
+
+```ts
+const unsubscribe = app.getDatabase
+  .collection("messages")
+  .query
+  .where({ key: "roomId", op: "==", value: "general" })
+  .onChildListener({
+    onChildAdded(snapshot) {
+      console.log("room message:", snapshot.data);
+    },
+  });
 ```
 
-## 📚 API Reference
+Child listener callback context includes:
+
+- `snapshots`: the current full query result
+- `source`: `"initial" | "insert" | "update" | "delete"`
+- `changedDocId`: the document that triggered the emission
+- `fromCache`: whether the emission came from local cache
+- `oldIndex`: previous index in the result set
+- `newIndex`: next index in the result set
+- `previousDoc`: previous version of the document when available
+
+## Collections and Documents
+
+### Get all documents
+
+```ts
+const users = await app.getDatabase.collection("users").get();
+
+users.forEach((user) => {
+  console.log(user.id, user.data);
+});
+```
 
-### Database Operations
+### Get one document
 
-```typescript
-// Get collection
-const collection = app.getDatabase.collection("users");
+```ts
+const user = await app.getDatabase.collection("users").doc("user-1").get();
 
-// Get all documents
-const users = await collection.get();
+if (user) {
+  console.log(user.data);
+}
+```
 
-// Get specific document
-const user = await collection.doc("user-id").get();
+### Create with generated id
 
-// Create/update document
-await collection.doc("user-id").set({
-  name: "John Doe",
-  email: "john@example.com"
+```ts
+const created = await app.getDatabase.collection("messages").add({
+  text: "Hello world",
+  roomId: "general",
+  createdAt: Date.now(),
 });
+```
 
-// Update document
-await collection.doc("user-id").update({
-  lastLogin: new Date()
+### Set a known id
+
+```ts
+await app.getDatabase.collection("users").doc("user-1").set({
+  name: "Jane",
+  email: "jane@example.com",
 });
+```
 
-// Delete document
-await collection.doc("user-id").delete();
+### Update a document
 
-// Real-time listeners
-const unsubscribe = collection.onSnapshot((snapshot) => {
-  console.log("Collection updated:", snapshot.docs);
+```ts
+await app.getDatabase.collection("users").doc("user-1").update({
+  lastLoginAt: Date.now(),
 });
 ```
 
-### Real-time Listeners
-
-```typescript
-// Document listener
-const unsubscribeDoc = app.getDatabase.collection("users").doc("user-id").onSnapshot(
-  (snapshot, change) => {
-    console.log("Document:", snapshot?.data());
-  }
-);
-
-// Collection listener
-const unsubscribeCollection = app.getDatabase.collection("messages").onSnapshot(
-  (documents, change) => {
-    console.log("Messages:", documents.map(doc => doc.data()));
-  }
-);
-
-// Cleanup when done
-unsubscribeDoc();
-unsubscribeCollection();
+### Delete a document
+
+```ts
+await app.getDatabase.collection("users").doc("user-1").delete();
 ```
 
-### Storage Operations
+## Queries
 
-```typescript
-// Upload file
-const ref = app.getStorage.ref("avatars/user-id.jpg");
-await ref.put(file);
+Build queries with `collection.query.where(...)`.
 
-// Get download URL
-const url = await ref.getDownloadURL();
+```ts
+const activeUsers = await app.getDatabase
+  .collection("users")
+  .query
+  .where({ key: "status", op: "==", value: "active" })
+  .where({ key: "age", op: ">=", value: 18 })
+  .get();
+```
 
-// Delete file
-await ref.delete();
+Supported operators:
+
+- `==`
+- `===`
+- `!=`
+- `<`
+- `<=`
+- `>`
+- `>=`
+- `in`
+- `nin`
+- `contains`
+
+Query snapshots are supported too:
+
+```ts
+const unsubscribe = app.getDatabase
+  .collection("users")
+  .query
+  .where({ key: "status", op: "==", value: "active" })
+  .onSnapshot((snapshots) => {
+    console.log("active users:", snapshots.map((doc) => doc.data));
+  });
 ```
 
-### Authentication
+## Offline Persistence
 
-```typescript
-// Get current user
-const user = app.getAuthentication.currentUser;
+Enable it with `persistence: true`.
 
-// Listen to auth changes
-const unsubscribe = app.getAuthentication.onAuthStateChanged((user) => {
-  console.log("User:", user);
+```ts
+const app = new EdmaxLabs({
+  token: "your-api-token",
+  project: "your-project-id",
+  persistence: true,
 });
 ```
 
-## 🛡️ Production Considerations
+What you get:
 
-### Memory Leak Prevention
+- local cached reads
+- optimistic local writes
+- background sync when the network returns
+- realtime listeners backed by the local cache first
 
-**Always cleanup listeners** when components unmount:
+Useful helpers:
 
-```tsx
-function MyComponent() {
-  useEffect(() => {
-    const unsubscribe = app.getDatabase.collection("items").onSnapshot(callback);
-    return unsubscribe; // ✅ Critical: prevent memory leaks
-  }, []);
-}
-```
+```ts
+app.isOfflineEnabled;
 
-### Error Handling
+await app.sync();
+await app.retrySync();
 
-```typescript
-try {
-  const result = await app.getDatabase.collection("users").doc("id").set(data);
-} catch (error) {
-  if (error.message.includes("quota exceeded")) {
-    // Handle storage full
-    alert("Storage is full. Please clear data.");
-  }
-}
+const failed = await app.getFailedMutations();
+console.log(failed);
+
+const usage = await app.getStorageUsage();
+console.log(usage);
+
+await app.clearCache();
+
+const offline = app.offline();
+console.log(offline.enabled);
+console.log(offline.getListenerCount());
 ```
 
-### Error Handling
-
-```typescript
-try {
-  const result = await app.getDatabase.collection("users").doc("id").set(data);
-} catch (error) {
-  if (error.message.includes("quota exceeded")) {
-    // Handle storage full
-    alert("Storage is full. Please clear some data.");
-  } else if (error.message.includes("Network")) {
-    // Handle offline
-    console.log("Will sync when online");
-  }
-}
+## Authentication
+
+### Current user
+
+```ts
+const user = app.getAuthentication.currentUser();
+console.log(user);
 ```
 
-### Storage Limits
+### Auth state listener
+
+```ts
+const unsubscribe = app.getAuthentication.authState({
+  onChange(user) {
+    console.log("signed in:", user);
+  },
+  onSignOut() {
+    console.log("signed out");
+  },
+  onDeleted() {
+    console.log("user deleted");
+  },
+});
+```
 
-Monitor storage usage to prevent quota issues:
+### Create account
 
-```typescript
-const { usage } = await app.getStorageUsage();
-if (usage && usage.used > usage.available * 0.8) {
-  console.warn("Storage usage is over 80%");
-}
+```ts
+const user = await app.getAuthentication.createUserWithEmailAndPassword({
+  email: "jane@example.com",
+  password: "secret123",
+});
 ```
 
-### Input Validation
+### Sign in
+
+```ts
+const user = await app.getAuthentication.signInWithEmailAndPassword({
+  email: "jane@example.com",
+  password: "secret123",
+});
+```
 
-The SDK validates inputs automatically, but you should also validate:
+### Sign out
 
-```typescript
-// These will throw errors:
-await doc.set(null);           // Error: data cannot be null
-await doc.set({ id: "123" });  // Error: 'id' is reserved
-await doc.set([]);             // Error: data cannot be an array
+```ts
+await app.getAuthentication.signOut();
 ```
 
-## 🧪 Testing
+## Storage
 
-```bash
-# Run tests
-npm test
+```ts
+const uploaded = await app.getStorage.upload(file);
+console.log(uploaded);
+
+const fileMeta = await app.getStorage.get("file-id");
+const fileInfo = await app.getStorage.getMeta("file-id");
 
-# Run tests in watch mode
-npm run test:watch
+await app.getStorage.delete("file-id");
+```
 
-# Run tests with coverage
-npm run test:coverage
+## Cloud Functions
+
+```ts
+const result = await app.getFunctions.call("sendWelcomeEmail", {
+  userId: "user-1",
+});
 
-# Type checking
-npm run lint
+console.log(result);
 ```
 
-## 📖 Documentation
+## Batch Writes
+
+```ts
+const db = app.getDatabase;
+const batch = db.batch();
+
+batch.set(db.collection("users").doc("u1"), {
+  name: "Jane",
+});
+
+batch.update(db.collection("users").doc("u2"), {
+  online: true,
+});
+
+batch.delete(db.collection("users").doc("u3"));
+
+await batch.commit();
+```
 
-- [Full API Reference](https://edmaxlabs.com/docs/api)
-- [Migration Guide](https://edmaxlabs.com/docs/migration)
-- [Best Practices](https://edmaxlabs.com/docs/best-practices)
+## Important Notes
 
-## 🤝 Contributing
+- Always unsubscribe realtime listeners in React `useEffect` cleanup.
+- `onSnapshot` returns full results for collections and queries.
+- `onChildListener` gives you granular callbacks like Firestore.
+- With persistence enabled, listeners can emit cached data first and then refresh with synced data.
+- Query results while offline reflect the latest local cache available on that device.
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md).
+## Minimal React Pattern
 
-## 📄 License
+```tsx
+useEffect(() => {
+  const unsubscribe = app.getDatabase
+    .collection("messages")
+    .onChildListener({
+      onChildAdded(snapshot) {
+        console.log("new message", snapshot.data);
+      },
+      onChildUpdated(snapshot) {
+        console.log("edited message", snapshot.data);
+      },
+      onChildRemoved(snapshot) {
+        console.log("deleted message", snapshot.id);
+      },
+    });
+
+  return unsubscribe;
+}, []);
+```
 
-MIT License - see [LICENSE](LICENSE) file for details.
-- [https://edmaxlabs.com/docs/database](https://edmaxlabs.com/docs/database)
----
+## Manual SDK Testing
 
-## Who is this for?
+There is now a manual browser test harness inside this repo.
 
-* Frontend developers (React, Vite, Next.js, HTML)
-* Backend developers (Node.js)
-* Teams building real-time apps or SaaS platforms
+Build the SDK:
 
----
+```bash
+npm run manual:test
+```
 
-## Security
+Start the local static server:
 
-* Client tokens are **public**
-* Access is enforced via **rules and server validation**
-* This SDK provides **access**, not authority
+```bash
+npm run manual:test:serve
+```
 
----
+Then open:
 
-## Ecosystem
+```text
+http://localhost:4173/manual-tests/index.html
+```
 
-* **edmaxlabs-tools** → CLI for managing projects, hosting, and rules
-* **edmaxlabs-core** → Runtime SDK for applications
+What you can verify there:
 
----
+- `collection.onSnapshot(...)`
+- `query.onSnapshot(...)`
+- `document.onSnapshot(...)`
+- `collection.onChildListener(...)`
+- create, set, update, delete flows
+- persistence-enabled behavior in the browser
+- offline/online transitions using devtools network controls
+- multiple active listeners at once
 
-## 🧠 Vision
+## License
 
-> Build once. Scale everywhere.
+MIT