@jcbuisson/express-x

v4.0.5

Published

21 days ago

Full doc: [https://expressx.jcbuisson.dev](https://expressx.jcbuisson.dev)

0High
0Medium
0Low

jcbuisson

Full doc: https://expressx.jcbuisson.dev

Getting started

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.

Plugins add new features: a 'reload' plugin preserve connection accross page reloads; an 'electric' plugin add a CRUD API, local-first, to a Postgres database.

mkdir myproject
cd myproject
mkdir backend frontend

Initialize backend

The server API is exported by @jcbuisson/express-x/server.

cd backend
npm init es6
npm install @jcbuisson/express-x cors

Back-end example with a custom service

The following example provides a 'math' service with two custom functions 'square' and 'cube':

// app.js
import { expressX } from '@jcbuisson/express-x/server';
import cors from 'cors'

// `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());

// 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`));

A service may have as many parameters as needed, of any types as long as they are serializable.

Run back-end

node app.js

Initialize front-end

The browser API is exported by @jcbuisson/express-x/client.

cd frontend
npm init es6
npm install @jcbuisson/express-x socket.io-client

Front-end example

index.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>

<script type="module">
import io from 'socket.io-client';
import { createClient } from '@jcbuisson/express-x/client';

const socket = io('http://localhost:8000', {
   transports: ["websocket"],
});

const app = createClient(socket);

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;
})

cubeBtn.addEventListener('click', async (ev) => {
   const result = await app.service('math').cube(valueInput.value);
   resultParagraph.innerHTML = result;
})
</script>

Run front-end

npx vite

Calling a service method from the frontend is as easy as await app.service('math').square(value)

Add a CRUD API over a relational database

It is very easy to expose the data access method of an ORM such as Prisma through ExpressX. The following example uses SQLite so it needs no database server.

Install and initialize Prisma:

npm install @prisma/client @prisma/adapter-better-sqlite3 dotenv
npm install --save-dev prisma
npx prisma init --datasource-provider sqlite --output ../generated/prisma

Define one model:

// prisma/schema.prisma
generator client {
   provider = "prisma-client"
   output   = "../generated/prisma"
}

datasource db {
   provider = "sqlite"
}

model Post {
   id      Int    @id @default(autoincrement())
   title   String
   content String?
}

Configure the SQLite file:

// prisma.config.ts
import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
   schema: 'prisma/schema.prisma',
   migrations: {
      path: 'prisma/migrations',
   },
   datasource: {
      url: env('DATABASE_URL'),
   },
})

# .env
DATABASE_URL="file:./dev.db"

Create the database and generate Prisma Client:

npx prisma migrate dev --name init
npx prisma generate

Finally, expose the model through an ExpressX service:

// app.js
import 'dotenv/config'
import { expressX } from '@jcbuisson/express-x/server'
import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3'
import { PrismaClient } from './generated/prisma/client.ts'

const adapter = new PrismaBetterSqlite3({
   url: process.env.DATABASE_URL,
})
const prisma = new PrismaClient({ adapter })
const app = expressX()

app.createService('post', {
   create: (data) => prisma.post.create({ data }),
   findMany: (where = {}) => prisma.post.findMany({ where }),
   update: (id, data) => prisma.post.update({ where: { id }, data }),
   remove: (id) => prisma.post.delete({ where: { id } }),
})

app.httpServer.listen(8000)

For production, add authentication and authorization hooks before exposing these methods to clients.

The client calls these methods through the normal service proxy:

const created = await app.service('post').create({
   title: 'Hello',
   content: 'Stored with Prisma',
})

const posts = await app.service('post').findMany()
await app.service('post').update(created.id, { title: 'Updated' })
await app.service('post').remove(created.id)

This service requires a network connection and does not provide synchronized reactive reads. For an offline-capable PostgreSQL application, use the Electric integration, which combines authorized ExpressX mutations with Electric Shape streams.

By default, errors on the server-side are serialized and re-emitted on the client-side, so you can catch them if needed.

Real-time applications

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.

For example in a medical application, whenever a patients's record is modified, an event could be sent to all his/her caregivers.

Channels are used for this pub/sub mechanism. Service methods publish events on channels, and clients subscribe 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.

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.

// app.js
// Run it with: `node app.js`
import { expressX } from '@jcbuisson/express-x/server';
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`));

<!-- 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 { createClient } from '@jcbuisson/express-x/client';

const socket = io('http://localhost:8000', {
   transports: ["websocket"],
});

const app = createClient(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: real-time updates with Electric

For database-backed reactive data, configure the Electric plugins. ExpressX authorizes and executes PostgreSQL mutations, while Electric streams the resulting rows to clients.

// app.js
import { Pool } from 'pg'
import { expressX } from '@jcbuisson/express-x/server'
import { electricOfflinePlugin } from '@jcbuisson/express-x-plugins/electric-server'

const app = expressX()
const db = new Pool({ connectionString: process.env.DATABASE_URL })

app.configure(electricOfflinePlugin, db, ['post'], {
   electricUrl: process.env.ELECTRIC_URL,
   authorize: async (context, operation) => {
      const user = context.request?.user ?? context.socket?.data?.user
      return Boolean(user && canAccess(user, operation))
   },
})

app.httpServer.listen(8000)

On the client, subscribe to a filtered Shape:

import io from 'socket.io-client'
import { createClient } from '@jcbuisson/express-x/client'
import { electricClientPlugin } from '@jcbuisson/express-x-plugins/electric-client'

const socket = io('http://localhost:8000', { transports: ["websocket"] })

const app = createClient(socket)
app.configure(electricClientPlugin)

const post = app.createElectricModel('post')
const subscription = post.getObservable({ published: true }).subscribe(posts => {
   console.log('Published posts', posts)
})

await post.create({ title: 'Hello', published: true })

See the Electric guide for model configuration, filters, authorization, and cleanup.