socio

library1.15.16jsnpmunverified

A WebSocket Real-Time Communication (RTC) API framework for building reactive front-end and back-end applications. Current stable version 1.15.16, released regularly. Key differentiator: allows writing SQL in frontend code that automatically syncs across all clients upon data changes; also provides real-time server props for generic data synchronization. Agnostic of framework, build tool, server library, and SQL database. Requires Node.js >= 16 LTS. Ships TypeScript definitions.

database messaging

npm install socio

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SOCIO

socio

databasejavascriptv1.15.16

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SocioServer

✓ import { SocioServer } from 'socio/dist/core-server'

✗ import { SocioServer } from 'socio'

SocioServer is not exported from the main entry; must import from 'socio/dist/core-server'.

SocioClient

✓ import { SocioClient } from 'socio/dist/core-client'

✗ const SocioClient = require('socio/dist/core-client')

ESM-only package; CommonJS require may fail or require .mjs extension. Client-side import from 'socio/dist/core-client'.

SocioSecurity

✓ import { SocioSecurity } from 'socio/dist/secure'

✗ import { SocioSecurity } from 'socio'

SocioSecurity is in 'socio/dist/secure' module, not main export. Used for encrypting SQL queries.

SocioSession

✓ import { SocioSession } from 'socio/dist/core-server'

✗ import { SocioSession } from 'socio'

Type for the session object in QueryWrap callback; exported from core-server.

Sets up a Socio server and client, establishes WebSocket connection, executes a parameterized SQL query.

import { SocioServer } from 'socio/dist/core-server'; import { SocioSecurity } from 'socio/dist/secure'; import { SocioClient } from 'socio/dist/core-client'; // Server (Node.js) const socsec = new SocioSecurity({ secure_private_key: 'my-secret-key', logging: { verbose: false } }); const socserv = new SocioServer({ port: 3000 }, { db: { Query: async (client, id, sql, params) => { // Simulate database query; replace with actual DB call return [{ id: 1, name: 'Alice' }]; } }, socio_security: socsec, logging: { verbose: false } }); // Client (browser) const client = new SocioClient('ws://localhost:3000'); await client.Connect(); const result = await client.Query('SELECT * FROM users WHERE id = ?', [1]); console.log(result); client.Disconnect();

Debug

Known issues

gotchaImport paths differ for server vs client: 'socio/dist/core-server' vs 'socio/dist/core-client'.

fix

Use correct subpath imports: for server 'socio/dist/core-server', for client 'socio/dist/core-client', for security 'socio/dist/secure'.

affects: >=1.0.0

gotchaSQL queries in frontend code are encrypted with AES-256-GCM; the encryption key must match between SocioSecurity and SocioSecurityVitePlugin.

fix

Ensure the same 'secure_private_key' is used in both server-side SocioSecurity instance and the Vite plugin during build.

affects: >=1.0.0

breakingSocioClient methods like .Query() and .Subscribe() are async and may throw if connection is not established.

fix

Always await .Connect() before calling query/subscribe methods. Handle connection errors with try-catch.

affects: >=1.0.0

deprecatedRequire() calls may not work in ESM-only environments; package is ESM-only since version 1.x.

fix

Use dynamic import() or configure your project to use ESM. Avoid CommonJS require.

affects: >=1.0.0

gotchaThe QueryWrap function on server must return a promise that resolves to an array or object; otherwise undefined behavior.

fix

Ensure QueryWrap is async and returns the expected data structure (e.g., array of rows).

affects: >=1.0.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

Trying to use ESM imports in a CommonJS project or without type:'module' in package.json.

fix

Add "type": "module" to your package.json or use .mjs extension for import files.

TypeError: socio_core_1.SocioClient is not a constructor

Importing from wrong path (e.g., 'socio' instead of 'socio/dist/core-client').

fix

Use correct import: import { SocioClient } from 'socio/dist/core-client';

ReferenceError: exports is not defined in ES module scope

Mixing CommonJS module.exports with ESM imports in the same file.

fix

Use ESM import/export exclusively. Remove module.exports and use export default / export.

ERR_REQUIRE_ESM: require() of ES Module not supported

Using require() to load Socio which is an ESM-only package.

fix

Switch to dynamic import() or convert your project to ESM. Use import syntax.

Upgrade

Version history

1.15.16latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Rolands-Laucis/Socio ↗

packagesocio ↗

homepagehttps://github.com/Rolands-Laucis/Socio#readme ↗