npm - @jcbuisson/express-x - Versions diffs - 2.1.20 → 3.0.1 - Mend

@jcbuisson/express-x 2.1.20 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md +207 -136
package/package.json +3 -3
package/src/{index.mjs → server.mjs} +283 -2

package/README.md CHANGED Viewed

@@ -1,172 +1,153 @@
+Full doc: [https://expressx.jcbuisson.dev](https://expressx.jcbuisson.dev)
-# Getting started
-## Create a project
-Let's create a new folder for our application:
-```bash
-mkdir expressx-project
-cd expressx-project
-```
+# Getting started
-Since any ExpressX application is a Node application, we can create a default package.json using npm:
+ExpressX is a framework handling both backend and frontend and their communication using websockets.\
+A single websocket is used to channel both data and events between the server and each client.
 ```bash
-npm init es6 --yes
+mkdir myproject
+cd myproject
+mkdir backend frontend
 ```
-The `es6` argument adds `"type": "module"` in `package.json`. Beware! All further module imports must made with es6/esm `import` syntax.
+## Initialize backend
-## Install ExpressX
+`@jcbuisson/express-x` is the server-side library
 ```bash
-npm install @jcbuisson/express-x
+cd backend
+npm init es6
+npm install @jcbuisson/express-x cors
 ```
-## Our first server application
+## Back-end example with a custom service
-Now we can create an ExpressX application which will provide a complete REST API on a `user` resource
-backed in a [Prisma](https://www.prisma.io/) database
+The following example provides a 'math' service with two custom functions 'square' and 'cube':
 ```js
 // app.js
-import { expressXServer } from '@jcbuisson/express-x'
+import { expressX } from '@jcbuisson/express-x';
+import cors from 'cors'
-// `app` is a regular express application, enhanced with service and real-time features
-const app = expressX()
+// `app` is a regular express application, enhanced with express-x services and real-time features
+const app = expressX();
+// regular express middleware, to allow access from our front-end
+app.use(cors());
-// configure prisma client from schema
-const prisma = new PrismaClient()
+// create a custom 'math' service with 2 methods
+app.createService('math', {
+   square: (x) => x*x,
+   cube: (x) => x*x*x,
+});
+app.httpServer.listen(8000, () => console.log(`App listening at http://localhost:8000`));
+```
-// create two CRUD database services. They provide Prisma methods: `create`, 'createMany', 'find', 'findMany', 'upsert', etc.
-app.createService('User', prisma.User)
-app.createService('Post', prisma.Post)
+A service may have as many parameters as needed, of any types as long as they are serializable.
-app.server.listen(8000, () => console.log(`App listening at http://localhost:8000`))
+## Run back-end
+```
+node app.js
 ```
-Before running it we need to setup the corresponding database.
+## Initialize front-end
+`@jcbuisson/express-x-client` is the client-side library
-## Create the database
+```bash
+cd frontend
+npm init es6
+npm install @jcbuisson/express-x-client socket.io-client
+```
-Presently, ExpressX only handles [Prisma](https://www.prisma.io/). Prisma is able to connect to most brands of relational or NoSQL databases.
+## Front-end example
-First, provide the database schema in `prisma/schema.prisma`:
-```prisma
-generator client {
-   provider = "prisma-client-js"
-}
+index.html
-model User {
-   id          Int       @default(autoincrement()) @id
-   name        String
-   posts       Post[]
-}
+```html
+<html>
+   <input id="value-id" type="number" placeholder="Enter value"><br>
+   <button id="square-id" class="btn">Square</button>
+   <button id="cube-id" class="btn">Cube</button>
+   <p id="result-id"></p>
+</html>
-model Post {
-   id          Int       @default(autoincrement()) @id
-   text        String
-   author      User      @relation(fields: [authorId], references: [id], onDelete: Cascade)
-   authorId    Int
-}
+<script type="module">
+import io from 'socket.io-client';
+import expressXClient from '@jcbuisson/express-x-client';
-datasource db {
-   provider = "sqlite"
-   url      = "file:./dev.db"
-}
-```
+const socket = io('http://localhost:8000', {
+   transports: ["websocket"],
+});
-Then create the database:
-```bash
-npx prisma db push
-```
+const app = expressXClient(socket);
-The sqlite database file is created at `prisma/dev.db`
+const valueInput = document.getElementById('value-id');
+const squareBtn = document.getElementById('square-id');
+const cubeBtn = document.getElementById('cube-id');
+const resultParagraph = document.getElementById('result-id');
+squareBtn.addEventListener('click', async (ev) => {
+   const result = await app.service('math').square(valueInput.value);
+   resultParagraph.innerHTML = result;
+})
-## Run the application on the server side
+cubeBtn.addEventListener('click', async (ev) => {
+   const result = await app.service('math').cube(valueInput.value);
+   resultParagraph.innerHTML = result;
+})
+</script>
+```
-```bash
-node app.js
+## Run front-end
+```
+npx vite
 ```
+Calling a service method from the frontend is as easy as `await app.service('math').square(value)`
-## Use it with a websocket client
-Create the following client NodeJS script:
+## Add a CRUD API over a relational database
-```js
-// client.js
-import io from 'socket.io-client'
-import { expressXClient } from '@jcbuisson/express-x'
+With a few more lines to the backend, we can add a complete CRUD API on a `User` resource
+backed in a [Prisma](https://www.prisma.io/) database
-const socket = io('http://localhost:8000', { transports: ["websocket"] })
+```js
+// app.js
+import { expressX } from '@jcbuisson/express-x'
+import { PrismaClient } from '@prisma/client'
-const app = expressXClient(socket)
+const prisma = new PrismaClient()
-async function main() {
-   const user = await app.service('User').create({
-      name: "Joe",
-   })
-   await app.service('Post').create({
-      authorId: user.id,
-      text: "Post#1"
-   })
-   await app.service('Post').create({
-      authorId: user.id,
-      text: "Post#2"
-   })
-   const joe = await app.service('User').findUnique({
-      where: {
-         id: user.id,
-      },
-      include: {
-         posts: true,
-      },
-   })
-   console.log('joe', joe)
-   process.exit(0)
-}
-main()
-```
+// `app` is a regular express application, enhanced with express-x services and real-time features
+const app = expressX()
-For simplicity we use a node client, but you would write something similar with your favorite front-end framework.
+...
-You can use the exact same statements on services on the client side as you would on the server side, such as: `app.service('User').create(...)`.
-Of course the `app` object here on the client is quite different that the `app` object on the server; you can find explanations [here]().
+// Create a CRUD database 'user' service with the Prisma methods: `create`, 'findUnique', etc.
+// Conveniently, `Prisma.User` is the map of all CRUD methods on User table
+app.createService('user', Prisma.User)
-Now run the client script:
-```bash
-node client.js
+app.httpServer.listen(8000, () => console.log(`App listening at http://localhost:8000`))
 ```
-It prints the following lines in the console:
-```json
-joe {
-  id: 11,
-  name: 'Joe',
-  posts: [
-    { id: 12, text: 'Post#1', authorId: 11 },
-    { id: 13, text: 'Post#2', authorId: 11 }
-  ]
-}
+Of course the database must be created and setup first.
+Now the full API of Prisma is accessible from the client-side, for example:
+```js
+const user = await app.service('user').findUnique({ where: { id: userId }})
 ```
-We have a GraphQL-like experience with the nested posts, thanks to Prisma and its use through ExpressX services.
+By default, errors on the server-side are serialized and re-emitted on the client-side, so you can catch them if needed.
-::: info
-We could have removed from `app.js` all lines related to HTTP, since we are only using the websocket transport.
-:::
 ## Real-time applications
-When websocket transport is used (default situation) and when a connected client calls a service method,
-two twings happen on method completion:
+When a connected client calls a service method, two things happen on method completion:
 - the resulting value is sent to the client
 - an event is emitted, and sent to connected clients we'll call subscribers. The calling client may or not be one of those subscribers.
@@ -177,50 +158,140 @@ For example in a medical application, whenever a patients's record is modified,
 to channels in order to receive those events. ExpressX provides functions to configure which events are published to which channels.
 A channel is represented by a name and you can create and use as many channels as you need.
-In the following example, every time a client connects to the server, it joins (= is subscribed to) the 'anonymous' channel.
+### Example: shared bilboard
+In the following example of a shared bilboard, every time a client connects to the server, it joins (= is subscribed to) the 'all' channel.
+And whenever an event is emited by the `bilboard` service, this event is published on this channel,
+and then broacasted to all connected clients, leading to real-time updates.
+```js
+// app.js
+// Run it with: `node app.js`
+import { expressX } from '@jcbuisson/express-x';
+import cors from 'cors'
+// `app` is a regular express application, enhanced with express-x services and real-time features
+const app = expressX();
+// express middleware which prevents cors issues with dev front-end
+app.use(cors());
+let bilboard = '';
+// create a custom 'bilboard' service with 1 method
+app.createService('bilboard', {
+   sendMessage: (message) => {
+      bilboard = message;
+      return message;
+   }
+});
+// publish
+app.service('bilboard').publish(async (context) => {
+   return ['all']
+});
+// subscribe
+app.on('connection', (socket) => {
+   app.joinChannel('all', socket)
+})
+app.httpServer.listen(8000, () => console.log(`App listening at http://localhost:8000`));
+```
+```html
+<!-- index.html; run it with: npx vite -->
+<html>
+   <input id="message-id" type="text" placeholder="Enter message"><br>
+   <button id="send-id" class="btn">Send</button>
+   <div id="bilboard-id"></div>
+</html>
+<script type="module">
+import io from 'socket.io-client';
+import expressXClient from '@jcbuisson/express-x-client';
+const socket = io('http://localhost:8000', {
+   transports: ["websocket"],
+});
+const app = expressXClient(socket);
+const messageInput = document.getElementById('message-id');
+const sendBtn = document.getElementById('send-id');
+const bilboardDiv = document.getElementById('bilboard-id');
+sendBtn.addEventListener('click', async (ev) => {
+   await app.service('bilboard').sendMessage(messageInput.value);
+});
+app.service('bilboard').on('sendMessage', (message) => {
+   bilboardDiv.innerHTML = bilboardDiv.innerHTML + '<br>' + message;
+})
+</script>
+```
+The listener is triggered whenever the client receives from the server a `sendMessage` event from the `bilboard` service.
+This event is sent to all subscribers after the execution of `app.service('bilboard').sendMessage()` on the server.
+### Example : CRUD database
+In this other example, every time a client connects to the server, it joins (= is subscribed to) the 'anonymous' channel.
 And whenever an event is emited by the `post` or `user` service, this event is published on this channel,
 and then broacasted to all connected clients, leading to real-time updates.
 ```js
 // app.js
-import { expressXServer } from '@jcbuisson/express-x'
-import { PrismaClient } from '@prisma/client'
+import { expressX } from '@jcbuisson/express-x';
+import { PrismaClient } from '@prisma/client';
-// `app` is a regular express application, enhanced with service and real-time features
-const app = expressX()
+const prisma = new PrismaClient();
-// configure prisma client from schema
-const prisma = new PrismaClient()
+// `app` is a regular express application, enhanced with express-x services and real-time features
+const app = expressX(prisma);
-// create two CRUD database services. They provide Prisma methods: `create`, 'createMany', 'find', 'findMany', 'upsert', etc.
-app.createService('User', prisma.User)
-app.createService('Post', prisma.Post)
+// create two CRUD database services with the Prisma methods: `create`, 'update', etc
+app.createService('user', prisma.User);
+app.createService('post', prisma.Post);
 // publish
-app.service('User').publish(async (post, context) => {
+app.service('user').publish(async (context) => {
    return ['anonymous']
-})
-app.service('Post').publish(async (post, context) => {
+});
+app.service('post').publish(async (context) => {
    return ['anonymous']
-})
+});
 // subscribe
-app.on('connection', (socket) => {
-   console.log('connection', socket.id)
+app.addConnectListener((socket) => {
    app.joinChannel('anonymous', socket)
-})
+});
-app.server.listen(8000, () => console.log(`App listening at http://localhost:8000`))
+app.httpServer.listen(8000, () => console.log(`App listening at http://localhost:8000`));
 ```
 Here is how a client may listen to channel events:
 ```js
-...
-app.service('Post').on('create', post => {
-   console.log('post event created', post)
+import io from 'socket.io-client'
+import expressXClient from '@jcbuisson/express-x-client'
+const socket = io('http://localhost:8000', { transports: ["websocket"] })
+const app = expressXClient(socket)
+app.service('user').on('create', (user) => {
+   console.log('User created', user)
+   // update client cache
+})
+app.service('post').on('create', (post) => {
+   console.log('Post created', post)
+   // update client cache
 })
 ```
 The listener is triggered whenever the client receives from the server a `create` event from the service `post`.
-This event results from the completion on the server of a call `app.service('Post').create()`
+This event is sent to all subscribers after the execution of `app.service('post').create()` on the server.

package/package.json CHANGED Viewed

@@ -1,12 +1,12 @@
 {
   "name": "@jcbuisson/express-x",
-  "version": "2.1.20",
+  "version": "3.0.1",
   "description": "",
   "type": "module",
-  "main": "src/index.mjs",
+  "main": "src/server.mjs",
   "repository": {
     "type": "git",
-    "url": "git@github.com:jcbuisson/express-x.git"
+    "url": "git+ssh://git@github.com/jcbuisson/express-x.git"
   },
   "author": "Jean-Christophe Buisson <buisson@enseeiht.fr> (jcbuisson.dev)",
   "license": "MIT",

package/src/{index.mjs → server.mjs} RENAMED Viewed

@@ -5,9 +5,51 @@ import bcrypt from 'bcryptjs'
 // UTILISER L'ACKNOWLEDGEMENT : https://socket.io/docs/v4/#acknowledgements
+//////////////////////////       UTILITIES       //////////////////////////
+function truncateString(str, maxLength = 300, ellipsis = '...') {
+   // Check if the string already fits
+   if (str.length <= maxLength) return str;
+   // Calculate the cut-off point, accounting for the ellipsis length
+   const cutLength = maxLength - ellipsis.length;
+   // Ensure the string is long enough to be cut
+   if (cutLength < 0) return str.substring(0, maxLength); // Just cut it off if ellipsis doesn't fit
+   // Truncate the string and add the ellipsis
+   return str.substring(0, cutLength) + ellipsis;
+}
+class Mutex {
+   constructor() {
+      this.locked = false;
+      this.queue = [];
+   }
+   async acquire() {
+      if (this.locked) {
+         return new Promise(resolve => this.queue.push(resolve));
+      }
+      this.locked = true;
+   }
+   release() {
+      if (this.queue.length > 0) {
+         const next = this.queue.shift();
+         next();
+      } else {
+         this.locked = false;
+      }
+   }
+}
+//////////////////////////       EXPRESSX       //////////////////////////
 export function expressX(config) {
    const services = {}
@@ -254,8 +296,8 @@ export function expressX(config) {
       return service
    }
-   function configure(callback) {
-      callback(app)
+   function configure(callback, ...args) {
+      callback(app, ...args)
    }
    // `app.service(name)` starts here!
@@ -336,3 +378,242 @@ export const protect = (field) => (context) => {
       }
    }
 }
+//////////////////////////       RELOAD PLUGIN       //////////////////////////
+export const roomCache = {}
+export const dataCache = {}
+export async function reloadPlugin(app) {
+   const io = app.get('io')
+   app.addDisconnectingListener((socket, reason) => {
+      console.log('onSocketDisconnecting', socket.id, reason)
+      // save socket data & rooms in caches
+      const alreadySavedData = dataCache[socket.id]
+      const alreadySavedRooms = roomCache[socket.id]
+      dataCache[socket.id] = Object.assign({}, socket.data)
+      roomCache[socket.id] = new Set(socket.rooms)
+      if (alreadySavedData) dataCache[socket.id] = Object.assign(dataCache[socket.id], alreadySavedData)
+      if (alreadySavedRooms) roomCache[socket.id].add(alreadySavedRooms)
+   })
+   app.addConnectListener((socket) => {
+      console.log('onSocketConnect', socket.id)
+      // when client ask for transfer from fromSocketId to toSocketId
+      socket.on('cnx-transfer', async (fromSocketId, toSocketId) => {
+         app.log('verbose', `cnx-transfer from ${fromSocketId} to ${toSocketId}`)
+         console.log('dataCache', dataCache)
+         console.log('roomCache', roomCache)
+         // copy connection room & data from 'fromSocketId' to 'toSocketId'
+         const toSocket = io.sockets.sockets.get(toSocketId)
+         // data & rooms of fromSocketId are taken from dataCache and roomCache, since socket no longer exists
+         const fromSocketRooms = roomCache[fromSocketId]
+         if (toSocket && fromSocketRooms) {
+            // copy rooms
+            for (const room of fromSocketRooms) {
+               if (room === fromSocketId) continue // do not include room associated to socket#id
+               toSocket.join(room)
+            }
+            // copy data
+            toSocket.data = dataCache[fromSocketId]
+            // console.log('cnx-transfer data', toSocket.data)
+            // console.log('cnx-transfer rooms', toSocket.rooms)
+            // remove 'from' cache data
+            delete roomCache[fromSocketId]
+            delete dataCache[fromSocketId]
+            // send acknowlegment to toSocket
+            toSocket.emit('cnx-transfer-ack', fromSocketId, toSocketId)
+         } else {
+            console.log(`*** CNX TRANSFER ERROR, ${fromSocketId} -> ${toSocketId}`)
+            toSocket.emit('cnx-transfer-error', fromSocketId, toSocketId)
+         }
+      })
+   })
+}
+//////////////////////////       OFFLINE PLUGIN       //////////////////////////
+const mutex = new Mutex()
+export function offlinePlugin(app, modelNames) {
+   const prisma = app.get('prisma');
+   if (!prisma.metadata) {
+      app.log('error', "A model named 'metadata' is expected in the prisma database - see https://expressx.jcbuisson.dev/server-api.html#offline")
+      return
+   }
+   // add a database service for each model
+   for (const modelName of modelNames) {
+      const model = prisma[modelName];
+      app.createService(modelName, {
+         findUnique: model.findUnique,
+         findMany: model.findMany,
+         createWithMeta: async (uid, data, created_at) => {
+            const [value, meta] = await prisma.$transaction([
+               model.create({ data: { uid, ...data } }),
+               prisma.metadata.create({ data: { uid, created_at } })
+            ])
+            return [value, meta]
+         },
+         updateWithMeta: async (uid, data, updated_at) => {
+            const [value, meta] = await prisma.$transaction([
+               model.update({ where: { uid }, data }),
+               prisma.metadata.update({ where: { uid }, data: { updated_at } })
+            ])
+            return [value, meta]
+         },
+         deleteWithMeta: async (uid, deleted_at) => {
+            const [value, meta] = await prisma.$transaction([
+               model.delete({ where: { uid } }),
+               prisma.metadata.update({ where: { uid }, data: { deleted_at } })
+            ])
+            return [value, meta]
+         },
+      })
+   }
+   // add a synchronization service
+   app.createService('sync', {
+      // AMÉLIORER : ne pas avoir une exclusion mutuelle globale, mais seulement par model/where
+      go: async (modelName, where, cutoffDate, clientMetadataDict) => {
+         await mutex.acquire()
+         try {
+            console.log('>>>>> SYNC', modelName, where, cutoffDate)
+            const databaseService = app.service(modelName)
+            const prisma = app.get('prisma')
+            // STEP 1: get existing database `where` values
+            const databaseValues = await databaseService.findMany({ where })
+            const databaseValuesDict = databaseValues.reduce((accu, value) => {
+               accu[value.uid] = value
+               return accu
+            }, {})
+            // console.log('clientMetadataDict', clientMetadataDict)
+            // console.log('databaseValuesDict', databaseValuesDict)
+            // STEP 2: compute intersections between client and database uids
+            const onlyDatabaseIds = new Set()
+            const onlyClientIds = new Set()
+            const databaseAndClientIds = new Set()
+            for (const uid in databaseValuesDict) {
+               if (uid in clientMetadataDict) {
+                  databaseAndClientIds.add(uid)
+               } else {
+                  onlyDatabaseIds.add(uid)
+               }
+            }
+            for (const uid in clientMetadataDict) {
+               if (uid in databaseValuesDict) {
+                  databaseAndClientIds.add(uid)
+               } else {
+                  onlyClientIds.add(uid)
+               }
+            }
+            // console.log('onlyDatabaseIds', onlyDatabaseIds)
+            // console.log('onlyClientIds', onlyClientIds)
+            // console.log('databaseAndClientIds', databaseAndClientIds)
+            // STEP 3: build add/update/delete sets
+            const addDatabase = []
+            const updateDatabase = []
+            const deleteDatabase = []
+            const addClient = []
+            const updateClient = []
+            const deleteClient = []
+            for (const uid of onlyDatabaseIds) {
+               const databaseValue = databaseValuesDict[uid]
+               let databaseMetaData = await prisma.metadata.findUnique({ where: { uid }})
+               if (!databaseMetaData) {
+                  console.log('no metadata - should not happen', modelName, where, uid)
+                  databaseMetaData = { uid, created_at: new Date() }
+               }
+               addClient.push([databaseValue, databaseMetaData])
+            }
+            for (const uid of onlyClientIds) {
+               const clientMetaData = clientMetadataDict[uid]
+               if (clientMetaData.deleted_at) {
+                  deleteClient.push([uid, clientMetaData.deleted_at])
+               } else if (new Date(clientMetaData.created_at) > cutoffDate) {
+                  addDatabase.push(clientMetaData)
+               } else {
+                  // ???
+               }
+            }
+            for (const uid of databaseAndClientIds) {
+               const databaseValue = databaseValuesDict[uid]
+               const clientMetaData = clientMetadataDict[uid]
+                  || { uid, created_at: new Date() } // should not happen
+               if (clientMetaData.deleted_at) {
+                  deleteDatabase.push(uid)
+                  deleteClient.push([uid, clientMetaData.deleted_at])
+               } else {
+                  const databaseMetaData = await prisma.metadata.findUnique({ where: { uid }})
+                     || { uid, created_at: new Date() } // should not happen
+                  const clientUpdatedAt = new Date(clientMetaData.updated_at || clientMetaData.created_at)
+                  const databaseUpdatedAt = new Date(databaseMetaData.updated_at || databaseMetaData.created_at)
+                  const dateDifference = clientUpdatedAt - databaseUpdatedAt
+                  // console.log('databaseMetaData', databaseMetaData, 'clientMetaData', clientMetaData, 'dateDifference', dateDifference)
+                  if (dateDifference > 0) {
+                     updateDatabase.push(clientMetaData)
+                  } else if (dateDifference < 0) {
+                     updateClient.push(databaseValue)
+                  }
+               }
+            }
+            console.log('addDatabase', truncateString(JSON.stringify(addDatabase)))
+            console.log('deleteDatabase', truncateString(JSON.stringify(deleteDatabase)))
+            console.log('updateDatabase', truncateString(JSON.stringify(updateDatabase)))
+            console.log('addClient', truncateString(JSON.stringify(addClient)))
+            console.log('deleteClient', truncateString(JSON.stringify(deleteClient)))
+            console.log('updateClient', truncateString(JSON.stringify(updateClient)))
+            // STEP4: execute database deletions
+            for (const uid of deleteDatabase) {
+               const clientMetaData = clientMetadataDict[uid]
+               // console.log('---delete', uid, clientMetaData)
+               await databaseService.deleteWithMeta(uid, clientMetaData.deleted_at)
+            }
+            // STEP5: return to client the changes to perform on its cache, and create/update to perform on database with full data
+            // database creations & updates are done later by the client with complete data (this function only has client values's meta-data)
+            return {
+               toAdd: addClient,
+               toUpdate: updateClient,
+               toDelete: deleteClient,
+               addDatabase,
+               updateDatabase,
+            }
+         } catch(err) {
+            console.log('*** err sync', err)
+         } finally {
+            mutex.release()
+         }
+      },
+   })
+}