@logux/server 0.14.0 → 0.16.0

package/human-formatter/index.js

@@ -1,8 +1,9 @@
 import os from 'node:os'
 import { stripVTControlCharacters, styleText } from 'node:util'
 
-import { mulberry32, onceXmur3 } from './utils.js'
+import { isBinary, mulberry32, onceXmur3 } from './utils.js'
 
+const BINARY_MARK = '[binary]'
 const INDENT = '  '
 const PADDING = '        '
 const SEPARATOR = os.EOL + os.EOL
@@ -119,7 +120,9 @@ function formatNodeId(nodeId) {
 }
 
 function formatValue(value) {
-  if (typeof value === 'string') {
+  if (isBinary(value)) {
+    return styleText('bold', BINARY_MARK)
+  } else if (typeof value === 'string') {
     return '"' + styleText('bold', value) + '"'
   } else if (Array.isArray(value)) {
     return formatArray(value)
@@ -145,10 +148,7 @@ function formatActionId(id) {
   if (p.length === 1) {
     return p
   }
-  return (
-    `${styleText('bold', splitAndColorize(4, p[0]))} ` +
-    `${formatNodeId(p[1])} ${styleText('bold', p[2])}`
-  )
+  return `${styleText('bold', splitAndColorize(4, p[0]))} ${formatNodeId(p[1])}`
 }
 
 function formatParams(params, parent) {
@@ -164,7 +164,12 @@ function formatParams(params, parent) {
 
       let start = PADDING + rightPag(`${name}: `, maxName + 2)
 
-      if (name === 'Node ID' || (parent === 'Meta' && name === 'server')) {
+      if (isBinary(value)) {
+        return start + styleText('bold', BINARY_MARK)
+      } else if (
+        name === 'Node ID' ||
+        (parent === 'Meta' && name === 'server')
+      ) {
         return start + formatNodeId(value)
       } else if (
         parent === 'Meta' &&

package/human-formatter/utils.js

@@ -1,3 +1,17 @@
+export const BINARY = {
+  toJSON() {
+    return '[binary]'
+  }
+}
+
+export function isBinary(value) {
+  return (
+    value === BINARY ||
+    ArrayBuffer.isView(value) ||
+    value instanceof ArrayBuffer
+  )
+}
+
 export function onceXmur3(str) {
   let h = 1779033703 ^ str.length
   for (let i = 0; i < str.length; i++) {

package/index.d.ts

@@ -16,8 +16,15 @@ export {
   ServerMeta,
   wasNot403
 } from './base-server/index.js'
-export { ChannelContext, Context } from './context/index.js'
+export { Context, ConnectContext, ChannelContext } from './context/index.js'
 export { filterMeta } from './filter-meta/index.js'
+export {
+  PostgresDriver,
+  PostgresQuery,
+  PostgresRows,
+  PostgresStore,
+  PostgresStoreOptions
+} from './postgres-store/index.js'
 export {
   del,
   get,

package/index.js

@@ -8,6 +8,7 @@ export { ALLOWED_META } from './allowed-meta/index.js'
 export { BaseServer, wasNot403 } from './base-server/index.js'
 export { Context } from './context/index.js'
 export { filterMeta } from './filter-meta/index.js'
+export { PostgresStore } from './postgres-store/index.js'
 export { ResponseError } from './request/index.js'
 export { Server } from './server/index.js'
 export { TestClient } from './test-client/index.js'

package/package.json

@@ -1,25 +1,22 @@
 {
   "name": "@logux/server",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Build own Logux server",
   "keywords": [
-    "logux",
-    "server",
-    "framework",
-    "websocket",
-    "proxy",
+    "collaborative",
     "crdt",
-    "event sourcing",
     "distributed systems",
-    "collaborative"
+    "event sourcing",
+    "framework",
+    "logux",
+    "proxy",
+    "server",
+    "websocket"
   ],
-  "author": "Andrey Sitnik <andrey@sitnik.ru>",
-  "license": "MIT",
   "homepage": "https://logux.org/",
+  "license": "MIT",
+  "author": "Andrey Sitnik <andrey@sitnik.es>",
   "repository": "logux/server",
-  "engines": {
-    "node": "^20.0.0 || >=22.0.0"
-  },
   "type": "module",
   "types": "./index.d.ts",
   "exports": {
@@ -27,14 +24,15 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@logux/actions": "^0.5.0",
-    "@logux/core": "^0.10.0",
-    "cookie": "^1.0.2",
-    "fastq": "^1.19.1",
-    "nanoevents": "^9.1.0",
-    "nanoid": "^5.1.5",
-    "tinyglobby": "^0.2.14",
-    "url-pattern": "^1.0.3",
-    "ws": "^8.18.3"
+    "@logux/actions": "^0.7.2",
+    "@logux/core": "^0.11.6",
+    "cookie": "^2.0.1",
+    "fastq": "^1.20.1",
+    "nanoevents": "^10.0.0",
+    "nanoid": "^6.0.1",
+    "ws": "^8.21.3"
+  },
+  "engines": {
+    "node": "^22.5.0 || ^24.0.0 || >=26.0.0"
   }
 }

package/postgres-store/index.d.ts

@@ -0,0 +1,149 @@
+import type { ActionPackerMap } from '@logux/actions'
+import type {
+  Action,
+  AnyAction,
+  Criteria,
+  LogPage,
+  LogStore,
+  Meta
+} from '@logux/core'
+
+/**
+ * Logux declares these two, but does not export them, so they are taken
+ * from the methods not to repeat the definition here.
+ */
+type GetOptions = NonNullable<Parameters<LogStore['get']>[0]>
+type LastSynced = Awaited<ReturnType<LogStore['getLastSynced']>>
+
+/**
+ * Rows of the query. `pg` and PGlite keep them in the result object,
+ * `postgres` returns them as an array.
+ */
+export type PostgresRows =
+  | { rows: Record<string, unknown>[] }
+  | Record<string, unknown>[]
+
+/**
+ * Minimal database interface for the drivers, which the store does not
+ * support out of the box.
+ *
+ * ```js
+ * let query = (sql, params) => driver.run(sql, params)
+ * query.transaction = body => {
+ *   return driver.tx(tx => body((sql, params) => tx.run(sql, params)))
+ * }
+ *
+ * let store = new PostgresStore(query)
+ * ```
+ */
+export interface PostgresQuery {
+  (sql: string, params: unknown[]): Promise<PostgresRows>
+
+  /**
+   * Run the callback on a single connection inside a transaction.
+   *
+   * Without it `init()` can not lock the migrations, so two servers
+   * starting at the same moment can apply them twice.
+   */
+  transaction?: (body: (query: PostgresQuery) => Promise<void>) => Promise<void>
+}
+
+/**
+ * Database driver, which the store can use without any wrapper:
+ * `pg`’s `Pool` or `Client`, PGlite, or `postgres`.
+ *
+ * The parameters are `never[]`, so that the driver’s own stricter types
+ * for them still match this type.
+ */
+export type PostgresDriver =
+  | {
+      begin?(body: (tx: PostgresDriver) => Promise<unknown>): Promise<unknown>
+      unsafe(sql: string, params: never[]): Promise<unknown>
+    }
+  | {
+      connect?(): Promise<unknown>
+      query(sql: string, params: never[]): Promise<unknown>
+      transaction?(
+        body: (tx: PostgresDriver) => Promise<unknown>
+      ): Promise<unknown>
+    }
+
+export interface PostgresStoreOptions<Packers = Record<string, never>> {
+  /**
+   * How many entries to load by a single query in `get()`.
+   */
+  pageSize?: number
+
+  /**
+   * Packers to keep the binary parts of the action in the `blob` column
+   * instead of Base64 inside JSON. The key must be the `type` of the action.
+   *
+   * `zeroPacker` is always added, so this is only for custom actions.
+   */
+  packers?: Packers
+}
+
+/**
+ * Log store, which keeps actions in PostgreSQL.
+ *
+ * It takes the database of `pg`, `postgres`, or PGlite. For any other driver,
+ * pass the function to send the query, see {@link PostgresQuery}.
+ *
+ * ```js
+ * import { PostgresStore, Server } from '@logux/server'
+ * import { Pool } from 'pg'
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL })
+ * const store = new PostgresStore(pool)
+ * await store.init()
+ *
+ * const server = new Server(Server.loadOptions(process, {
+ *   minSubprotocol: 1,
+ *   subprotocol: 1,
+ *   root: import.meta.dirname,
+ *   store
+ * }))
+ * ```
+ */
+export class PostgresStore<
+  Packers extends ActionPackerMap<Packers> = Record<string, never>
+>
+  implements LogStore
+{
+  constructor(
+    db: PostgresDriver | PostgresQuery,
+    opts?: PostgresStoreOptions<Packers>
+  )
+
+  add(action: AnyAction, meta: Meta): Promise<false | Meta>
+
+  addReason(reasons: string[], criteria: Criteria): Promise<void>
+
+  byId(id: string): Promise<[Action, Meta] | [null, null]>
+
+  changeMeta(id: string, diff: Partial<Meta>): Promise<boolean>
+
+  clean(): Promise<void>
+
+  get(opts?: GetOptions): Promise<LogPage>
+
+  getLastAdded(): Promise<number>
+
+  getLastSynced(): Promise<LastSynced>
+
+  /**
+   * Bring the log tables to the latest version, creating them if they were
+   * not created by the application’s migration.
+   */
+  init(): Promise<void>
+
+  remove(id: string): Promise<[Action, Meta] | false>
+
+  removeReason(
+    reasons: string[],
+    criteria: Criteria,
+    callback: (action: Action, meta: Meta) => void
+  ): Promise<void>
+
+  setLastSynced(values: Partial<LastSynced>): Promise<void>
+}