owservable 1.6.3 → 1.7.3

package/README.md

@@ -1,169 +1,450 @@
 ![owservable](https://avatars0.githubusercontent.com/u/87773159?s=75)
 
-# Owservable backend
-
-[Reactive Stack JS](https://github.com/reactive-stack-js) replacement.
-
-See <a href="https://owservable.github.io/" target="_blank">owservable.github.io</a> for more info.
-
-Checkout my <a href="https://www.udemy.com/course/reactive-stack/" target="_blank">Reactive Stack Udemy course</a>.
-
-## :books: Documentation
-
-See the <a href="https://owservable.github.io/owservable/docs/" target="_blank">TypeDoc documentation</a>.
-
-### :traffic_light: Testing:
-
-See the <a href="https://owservable.github.io/owservable/coverage/" target="_blank">Test coverage</a>.
-
-## :clipboard: TODOs
-
-- Web Server abstraction
-- Database abstraction
-- Client-side datastore abstraction
-- Larga Data handling
-- Server-Side Events
-
-## :scroll: Uses
-
-- [Mongoose](https://mongoosejs.com)
-- [RxJS](https://rxjs.dev)
-- [Typescript](https://www.typescriptlang.org/)
-- [Chai](https://www.chaijs.com/)
-- [Mocha](https://mochajs.org/)
-- [NYC](https://istanbul.js.org/)
-
-## :floppy_disk: MongoDB Replica Set
-
-Make sure your MongoDB database is running as a Replica Set: http://stojadinovic.net/2020/07/05/mongodb-change-streams-on-localhost-with-nodejs/
+# Owservable
+
+A reactive backend library for Node.js applications that provides real-time MongoDB change streams, reactive data stores, and automated task scheduling. Built with RxJS and TypeScript.
+
+**Owservable is a replacement for [Reactive Stack JS](https://github.com/reactive-stack-js).**
+
+## 🚀 Features
+
+- **Real-time MongoDB Integration**: MongoDB change streams with reactive observables
+- **Reactive Data Stores**: Count, Document, and Collection stores with automatic updates
+- **WebSocket Client Management**: Built-in client connection and subscription handling
+- **Task Scheduling**: Automated cronjobs, watchers, and workers
+- **Action Pattern**: Structured business logic with multiple execution contexts
+- **Data Middleware**: Transform and filter data based on user permissions
+- **Type Safety**: Full TypeScript support with comprehensive type definitions
+
+## 📦 Installation
+
+```bash
+npm install owservable
+```
+
+or
+
+```bash
+yarn add owservable
+```
+
+or
+
+```bash
+pnpm add owservable
+```
+
+## 🏗️ Requirements
+
+- **Node.js**: >= 20
+- **MongoDB**: >= 3.6 (Replica Set required for change streams)
+- **TypeScript**: Recommended for full type safety
+
+## 🔧 MongoDB Setup
+
+Owservable requires MongoDB to be running as a Replica Set to enable change streams:
+
+```bash
+# Start MongoDB as a single-node replica set
+mongod --replSet rs0
+
+# Initialize the replica set
+mongo --eval "rs.initiate()"
+```
+
+For more details, see: [MongoDB Change Streams on localhost with Node.js](http://stojadinovic.net/2020/07/05/mongodb-change-streams-on-localhost-with-nodejs/)
+
+## 🚀 Quick Start
+
+### 1. Basic Server Setup
+
+```typescript
+import { 
+  OwservableClient, 
+  MongoDBConnector, 
+  processModels,
+  IConnectionManager 
+} from 'owservable';
+
+// Initialize MongoDB connection
+const mongoConnector = new MongoDBConnector();
+await mongoConnector.connect('mongodb://localhost:27017/myapp');
+
+// Process your Mongoose models
+await processModels('./models');
+
+// Implement connection manager
+class MyConnectionManager implements IConnectionManager {
+  async connected(jwt: string): Promise<void> {
+    // Handle client connection
+  }
+  
+  async disconnected(): Promise<void> {
+    // Handle client disconnection
+  }
+  
+  async checkSession(): Promise<any> {
+    // Handle session validation
+    return { refresh_in: 300000 };
+  }
+  
+  ping(ms: number): void {
+    // Handle ping updates
+  }
+  
+  location(path: string): void {
+    // Handle location updates
+  }
+  
+  get user(): any {
+    // Return current user
+    return this.currentUser;
+  }
+}
+
+// Create owservable client
+const connectionManager = new MyConnectionManager();
+const client = new OwservableClient(connectionManager);
+
+// Handle client messages
+client.subscribe({
+  next: (message) => {
+    // Forward to WebSocket clients
+    websocket.send(JSON.stringify(message));
+  },
+  error: (error) => console.error('Client error:', error)
+});
+```
+
+### 2. WebSocket Integration
+
+```typescript
+import { WebSocketServer } from 'ws';
+
+const wss = new WebSocketServer({ port: 8080 });
+
+wss.on('connection', (ws) => {
+  const client = new OwservableClient(connectionManager);
+  
+  // Subscribe to client updates
+  client.subscribe({
+    next: (message) => ws.send(JSON.stringify(message)),
+    error: (error) => console.error('Error:', error)
+  });
+  
+  // Handle incoming messages
+  ws.on('message', async (data) => {
+    const message = JSON.parse(data.toString());
+    await client.consume(message);
+  });
+  
+  // Handle disconnect
+  ws.on('close', () => {
+    client.disconnected();
+  });
+  
+  // Start ping
+  client.ping();
+});
+```
+
+### 3. Reactive Data Stores
+
+```typescript
+import { storeFactory, EStoreType } from 'owservable';
+
+// Count store - returns only document count
+const countStore = storeFactory(EStoreType.COUNT, 'users', 'user-count');
+countStore.config = {
+  query: { active: true },
+  fields: {}
+};
+
+// Collection store - returns array of documents
+const collectionStore = storeFactory(EStoreType.COLLECTION, 'users', 'user-list');
+collectionStore.config = {
+  query: { active: true },
+  fields: { name: 1, email: 1 },
+  sort: { name: 1 },
+  page: 1,
+  pageSize: 10
+};
+
+// Document store - returns single document
+const documentStore = storeFactory(EStoreType.DOCUMENT, 'users', 'user-profile');
+documentStore.config = {
+  query: { _id: 'user123' },
+  fields: { name: 1, email: 1, profile: 1 }
+};
+```
+
+### 4. Task Scheduling
+
+```typescript
+import { 
+  initiateCronjobs, 
+  initiateWatchers, 
+  initiateWorkers 
+} from 'owservable';
+
+// Initialize cronjobs
+await initiateCronjobs('./cronjobs');
+
+// Initialize file watchers
+await initiateWatchers('./watchers');
+
+// Initialize background workers
+await initiateWorkers('./workers');
+```
+
+### 5. Data Middleware
+
+```typescript
+import { DataMiddlewareMap } from 'owservable';
+
+// Register middleware for collection
+DataMiddlewareMap.set('users', async (payload, user) => {
+  // Filter sensitive data based on user permissions
+  if (!user.isAdmin) {
+    payload.data = payload.data.map(doc => ({
+      ...doc,
+      email: '***@***.***' // Hide emails for non-admins
+    }));
+  }
+  return payload;
+});
+```
+
+## 📚 Core Components
 
 ### OwservableClient
 
-This is the main class.
-
-It processes client subscription requests, creates appropriate stores and subscribes to them to observe changes.
-
-It extends RxJS:Subject, so that any websocket instance can subscribe to it, in order to forward updates back to the client.
-
-### IConnectionManager
-
-Defines a Connection`Manager interface to be implemented by the application using this library.
-
-This implementation is required for the above ```OwservableClient```. An instance of ```OwservableClient``` is calling ```IConnectionManager``` methods accordingly.
-
-### DataMiddlewareMap
-
-This is a map of all defined Data Middleware methods.
-
-A Data Middleware is tied to a collection name and is used to modify an observed payload if necessary. For example, if based on users
-access permissions a portion of the payload needs to be removed or replaced, etc.
-
-### initiateWatchers
-
-Method that initiates all watchers. Takes the project root folder path and a global folder name for the watchers.
-
-Watchers can either perform simple tasks or add jobs to a queue, to be processed by the workers.
-
-### initiateCronjobs
-
-Method that initiates all cronjobs. Takes the project root folder path and a global folder name for the cronjobs.
-
-Cronjobs can either perform simple tasks or add jobs to a queue, to be processed by the workers.
-
-### initiateWorkers
-
-Method that initiates all workers. Takes the project root folder path and a global folder name for the workers.
-
-Workers can either perform simple tasks or take jobs from a queue.
-
-## MongoDB
-
-### MongoDBConnector
-
-A MongoDB database connector class, used to initialize the database collection which Mongoose will then use.
-
-### processModels
-
-This method parses all models and adds them to the ```CollectionsModelsMap``` if they pass validation. The method takes the project root folder path and a global folder name for
-the models and an optional folder name(
-s) to exclude, for example ```mixins``` and similar.
-
-### CollectionsModelsMap
-
-This is a map of all Mongoose models and related MongoDB collections. It is populated automatically during the execution of ```processModels```.
-
-### observableModel
-
-Requires MongoDB 3.6+: This method returns an RxJS Subject that can be subscribed to and thus observe a particular MongoDB collection. This method takes a Mongoose model instance.
-
-### observableDatabase
-
-Requires MongoDB 4.0+: This method returns an RxJS Subject that can be subscribed to and thus observe the entire MongoDB database.
-
-## Routes
-
-### processFastifyBlipp
-
-This method stores all fastify routes into the ```RoutesMap``` in order to display them on request as a form of quick routes documentation.
-
-This method is set as ```blippLog``` options attribute during fastify registration of the ```fastify-blipp``` plugin.
-Eg. ```server.register(fastifyBlipp, {blippLog: processFastifyBlipp});```.
-
-### RoutesMap
-
-This is a map of all available routes. It is populated automatically during the execution of ```processFastifyBlipp```.
-
-### addFastifyRoutes
-
-This method adds all routes to fastify automatically. It requires as parameters a fastify instance, the project root folder path and a global folder name for the routes.
-
-### cleanRelativePath
-
-Helper metohd used in ```addFastifyRoutes``` to generate the route path from filename and file location relative to routes root folder.
-
-## Store
-
-### AStore
-
-Abstract class for ```CountStore```, ```DocumentStore``` and ```CollectionStore``` implementations.
-
-### EStoreType
-
-Enum for existing store types: ```COUNT | DOCUMENT | COLLECTION```.
-
-### CountStore
-
-Count store, observes a particular query and returns only an integer representing the count of response rows.
-
-### DocumentStore
-
-Document store, observes a particular query and returns all response rows.
-
-### CollectionStore
-
-Collection store, observes a particular query and returns all response rows.
-
-### storeFactory
-
-Store factory method, creates an appropriate AStore instance based on passed subscription parameters.
-
-## Types
-
-These types are self explanatory.
-
-- CronJobType
-- WatcherType
-- WorkerType
-- StoreScopeType
-- StoreSubscriptionConfigType
-- StoreSubscriptionUpdateType
-- ConnectionManagerRefreshType
-
-## :scroll: License
+The main client class that manages WebSocket connections and subscriptions:
+
+```typescript
+const client = new OwservableClient(connectionManager);
+
+// Handle different message types
+await client.consume({
+  type: 'subscribe',
+  target: 'user-list',
+  scope: 'collection',
+  observe: 'users',
+  config: {
+    query: { active: true },
+    fields: { name: 1, email: 1 }
+  }
+});
+```
+
+### Store Types
+
+#### CollectionStore
+Returns arrays of documents with real-time updates:
+
+```typescript
+const store = storeFactory(EStoreType.COLLECTION, 'posts', 'post-list');
+store.config = {
+  query: { published: true },
+  fields: { title: 1, content: 1, author: 1 },
+  sort: { createdAt: -1 },
+  populate: ['author'],
+  page: 1,
+  pageSize: 20,
+  incremental: true // Enable incremental updates
+};
+```
+
+#### CountStore
+Returns document counts with real-time updates:
+
+```typescript
+const store = storeFactory(EStoreType.COUNT, 'users', 'user-count');
+store.config = {
+  query: { active: true }
+};
+```
+
+#### DocumentStore
+Returns single documents with real-time updates:
+
+```typescript
+const store = storeFactory(EStoreType.DOCUMENT, 'users', 'current-user');
+store.config = {
+  query: { _id: userId },
+  fields: { name: 1, email: 1, preferences: 1 }
+};
+```
+
+### MongoDB Integration
+
+#### Observable Models
+Monitor MongoDB collections for changes:
+
+```typescript
+import { observableModel } from 'owservable';
+import UserModel from './models/User';
+
+const userObservable = observableModel(UserModel);
+userObservable.subscribe({
+  next: (change) => {
+    console.log('User collection changed:', change);
+  }
+});
+```
+
+#### Observable Database
+Monitor entire database for changes:
+
+```typescript
+import { observableDatabase } from 'owservable';
+
+const dbObservable = observableDatabase();
+dbObservable.subscribe({
+  next: (change) => {
+    console.log('Database changed:', change);
+  }
+});
+```
+
+### Action Pattern
+
+Create structured business logic with the action pattern:
+
+```typescript
+import { Action, ActionInterface } from 'owservable';
+
+class SendEmailAction extends Action implements ActionInterface {
+  protected _description = 'Send email notification';
+  
+  async handle(to: string, subject: string, body: string): Promise<void> {
+    // Email sending logic
+    console.log(`Sending email to ${to}: ${subject}`);
+  }
+  
+  description(): string {
+    return this._description;
+  }
+}
+
+// Use in cronjobs, workers, or watchers
+const emailAction = new SendEmailAction();
+await emailAction.handle('user@example.com', 'Welcome!', 'Hello World');
+```
+
+## 🔧 Configuration
+
+### Environment Variables
+
+```bash
+# MongoDB connection
+MONGODB_URI=mongodb://localhost:27017/myapp
+
+# WebSocket server
+WS_PORT=8080
+
+# JWT settings
+JWT_SECRET=your-secret-key
+JWT_EXPIRATION=24h
+```
+
+### TypeScript Configuration
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+## 📖 Advanced Usage
+
+### Custom Store Implementation
+
+```typescript
+import { AStore, EStoreType } from 'owservable';
+
+class CustomStore extends AStore {
+  constructor(model: Model<any>, target: string) {
+    super(model, target);
+    this._type = EStoreType.COLLECTION;
+  }
+  
+  protected async load(change: any): Promise<void> {
+    // Custom loading logic
+    const data = await this.customQuery();
+    this.emitMany(Date.now(), this._subscriptionId, { data });
+  }
+}
+```
+
+### Performance Optimization
+
+```typescript
+// Use incremental updates for large collections
+store.config = {
+  incremental: true,
+  page: 1,
+  pageSize: 50
+};
+
+// Optimize queries with indexes
+await addIndexToAttributes(model, ['field1', 'field2']);
+
+// Use field projection
+store.config = {
+  fields: { 
+    name: 1, 
+    email: 1,
+    _id: 0 // Exclude _id
+  }
+};
+```
+
+## 🧪 Testing
+
+```bash
+npm test
+```
+
+## 📖 Documentation
+
+- **Main Website**: [owservable.github.io](https://owservable.github.io/)
+- **TypeDoc Documentation**: [owservable.github.io/owservable/docs/](https://owservable.github.io/owservable/docs/)
+- **Test Coverage**: [owservable.github.io/owservable/coverage/](https://owservable.github.io/owservable/coverage/)
+- **Udemy Course**: [Reactive Stack Course](https://www.udemy.com/course/reactive-stack/)
+
+## 🔗 Related Projects
+
+- [@owservable/actions](https://github.com/owservable/actions) - Action pattern implementation
+- [@owservable/folders](https://github.com/owservable/folders) - File system utilities
+- [@owservable/fastify-auto-routes](https://github.com/owservable/fastify-auto-routes) - Fastify auto routing
+
+## 🛣️ Roadmap
+
+- [ ] Web Server abstraction
+- [ ] Database abstraction
+- [ ] Client-side datastore abstraction
+- [ ] Large Data handling
+- [ ] Server-Side Events
+- [ ] Redis integration
+- [ ] GraphQL subscriptions
+- [ ] Microservices support
+
+## 📄 License
 
 Licensed under [The Unlicense](./LICENSE).
 
-## :sparkles: Contributors
+## 🤝 Contributors
 
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
 <!-- prettier-ignore-start -->
@@ -196,6 +477,6 @@ This project follows the [all-contributors](https://github.com/all-contributors/
 
 Contributions of any kind welcome!
 
-## :chart_with_upwards_trend: UML
+## 📊 UML Diagram
 
-Checkout the [UML diagram](https://raw.githubusercontent.com/owservable/owservable/main/uml.png).
+Checkout the [UML diagram](https://raw.githubusercontent.com/owservable/owservable/main/uml.png) for a visual overview of the architecture.

package/lib/auth/i.connection.manager.d.ts

@@ -1,4 +1,4 @@
-import ConnectionManagerRefreshType from '../_types/connection.manager.refresh.type';
+import ConnectionManagerRefreshType from '../types/connection.manager.refresh.type';
 export default interface IConnectionManager {
     user(): any;
     connected(jwt: any): void;

package/lib/enums/store.type.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.type.enum.js","sourceRoot":"","sources":["../../src/enums/store.type.enum.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,IAAK,UAIJ;AAJD,WAAK,UAAU;IACd,mDAAQ,CAAA;IACR,uDAAU,CAAA;IACV,6CAAK,CAAA;AACN,CAAC,EAJI,UAAU,KAAV,UAAU,QAId;AAED,kBAAe,UAAU,CAAC"}

package/lib/functions/action/add.action.cronjobs.d.ts

@@ -1 +1 @@
-export default function addActionCronjobs(root: string, folderName: string): void;
+export default function addActionCronjobs(root: string, folderName: string): Promise<void>;

package/lib/functions/action/add.action.cronjobs.js

@@ -1,26 +1,32 @@
 'use strict';
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = addActionCronjobs;
 const lodash_1 = require("lodash");
 const folders_1 = require("@owservable/folders");
 const execute_cronjob_1 = require("../execute/execute.cronjob");
 function addActionCronjobs(root, folderName) {
-    const actionPaths = (0, folders_1.listSubfoldersFilesByFolderName)(root, folderName);
-    for (const actionPath of actionPaths) {
-        console.log('[@owservable] -> Initializing cronjob action', actionPath);
-        const ActionClass = require(actionPath).default;
-        const action = new ActionClass();
-        if ((0, lodash_1.isFunction)(action.schedule) && (0, lodash_1.isFunction)(action.asCronjob)) {
-            const job = {
-                schedule: action.schedule(),
-                job: action.asCronjob
-            };
-            if ((0, lodash_1.isFunction)(action.cronjobOptions))
-                (0, lodash_1.set)(job, 'options', action.cronjobOptions());
-            if ((0, lodash_1.isFunction)(action.asCronjobInit))
-                (0, lodash_1.set)(job, 'init', action.asCronjobInit());
-            (0, execute_cronjob_1.default)(job);
+    return __awaiter(this, void 0, void 0, function* () {
+        const actionPaths = yield (0, folders_1.listSubfoldersFilesByFolderName)(root, folderName);
+        for (const actionPath of actionPaths) {
+            console.log('[@owservable] -> Initializing cronjob action', actionPath);
+            const ActionClass = require(actionPath).default;
+            const action = new ActionClass();
+            if ((0, lodash_1.isFunction)(action.asCronjob)) {
+                const job = Object.assign(Object.assign({ schedule: action.schedule() }, (action.asCronjobInit && { init: action.asCronjobInit })), { job: action.asCronjob });
+                if ((0, lodash_1.isFunction)(action.asCronjobInit))
+                    (0, lodash_1.set)(job, 'init', action.asCronjobInit());
+                (0, execute_cronjob_1.default)(job);
+            }
         }
-    }
+    });
 }
 //# sourceMappingURL=add.action.cronjobs.js.map