{"id":41297,"library":"insite-subscriptions-server","title":"inSite Subscriptions Server","description":"Server-side pub/sub layer for the inSite framework (v2.4.0). Defines publications (named data sources), subscription handles, and WebSocket integration for real-time updates. Supports two data modes: object (arbitrary data via custom fetch with manual change notification) and map (MongoDB collection with query/projection/sort that reacts to Change Streams and sends diff updates). Published weekly on npm. Key differentiators: tight integration with inSite ecosystem (insite-ws, insite-users-server-ws), low-level and WS entry points, MongoDB Change Stream support, diff-based incremental updates for map mode, TypeScript types included.","status":"active","version":"2.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/nesvet/insite","tags":["javascript","insite","subscriptions","publications","server","typescript"],"install":[{"cmd":"npm install insite-subscriptions-server","lang":"bash","label":"npm"},{"cmd":"yarn add insite-subscriptions-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add insite-subscriptions-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides WatchedCollection for map mode publications","package":"insite-db","optional":false},{"reason":"Required for WebSocket integration (entry point insite-subscriptions-server/ws)","package":"insite-ws","optional":true},{"reason":"Required for user-specific WebSocket middleware (entry point insite-subscriptions-server/ws)","package":"insite-users-server-ws","optional":true}],"imports":[{"note":"Package is ESM-only since v2. CommonJS require() will not work. 'publications' is a global Map instance.","wrong":"const publications = require('insite-subscriptions-server').publications","symbol":"publications","correct":"import { publications } from 'insite-subscriptions-server'"},{"note":"No subpath export '/main' exists. Use default package path.","wrong":"import { Publication } from 'insite-subscriptions-server/main'","symbol":"Publication","correct":"import { Publication } from 'insite-subscriptions-server'"},{"note":"CollectionMapPublication is a named export, not default.","wrong":"import CollectionMapPublication from 'insite-subscriptions-server'","symbol":"CollectionMapPublication","correct":"import { CollectionMapPublication } from 'insite-subscriptions-server'"},{"note":"SubscriptionHandler is only exported from the WS entry point (insite-subscriptions-server/ws). It is not available from the main entry.","wrong":"import { SubscriptionHandler } from 'insite-subscriptions-server'","symbol":"SubscriptionHandler","correct":"import { SubscriptionHandler } from 'insite-subscriptions-server/ws'"},{"note":"Projection is a TypeScript type only, not a runtime value. Use 'import type' to avoid bundler issues.","wrong":"import { Projection } from 'insite-subscriptions-server'","symbol":"type Projection","correct":"import type { Projection } from 'insite-subscriptions-server'"}],"quickstart":{"code":"import { Publication, CollectionMapPublication } from 'insite-subscriptions-server';\nimport { SubscriptionHandler } from 'insite-subscriptions-server/ws';\nimport { WatchedCollection } from 'insite-db';\nimport { WebSocketServer } from 'ws';\n\n// Object publication\nconst pub = new Publication('myPub', {\n  fetch: (userId) => ({ user: userId, count: 42 })\n});\nsetInterval(() => pub.changed('time-update'), 10000);\n\n// Subscription handle\nconst handle = pub.subscribe({\n  args: ['user1'],\n  handler: (data, reason) => console.log('Got', data, 'reason:', reason)\n});\n\n// Map publication (requires insite-db)\nconst collection = new WatchedCollection('items');\nconst mapPub = new CollectionMapPublication('itemsPub', {\n  collection,\n  query: { userId: 'user1' },\n  projection: { _id: 1, name: 1, price: 1 },\n  sort: { createdAt: -1 }\n});\n\n// WS integration\nconst wss = new WebSocketServer({ port: 8080 });\nconst handler = new SubscriptionHandler(wss, {\n  authenticate: (ws, req) => ({ userId: 'user1' })\n});\nwss.on('connection', (ws, req) => handler.handleConnection(ws, req));\n\n// Server-wide publish\nimport { wss as globalWss } from 'insite-subscriptions-server/ws';\nglobalWss.publish('event', { message: 'Hello' });","lang":"typescript","description":"Creates an object publication, subscribes to it, sets up a MongoDB-backed map publication with Change Stream updates, integrates with WebSocket server, and sends server-wide publish event."},"warnings":[{"fix":"Use import syntax (import/await import). If you must use CJS, downgrade to v1.x or use dynamic import().","message":"Package is ESM-only since v2.0.0; CommonJS require() will throw ERR_REQUIRE_ESM.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use 'insite-subscriptions-server/ws' for all WebSocket-related imports. Remove imports from 'insite-subscriptions-server/users-server-ws'.","message":"Subpath exports changed in v2.0.0: '/ws' is now the only subpath for WebSocket integration. Previously '/users-server-ws' was separate.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update Node.js to 20+.","message":"Node.js >=20.0.0 is required; older versions are unsupported.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Avoid relying on 'publications' Map; instead keep references to created Publication instances.","message":"The 'publications' global Map is deprecated in favor of using instance methods directly. It will be removed in v3.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Implement reconnection logic for WatchedCollection and monitor Change Stream resume tokens.","message":"CollectionMapPublication requires a WatchedCollection from 'insite-db'. If the database connection is lost, Change Stream may silently stop producing updates.","severity":"gotcha","affected_versions":"*"},{"fix":"Ensure tsconfig has \"moduleResolution\": \"node\" (or \"bundler\") and \"esModuleInterop\": true.","message":"TypeScript types are shipped but require 'strict' or 'esModuleInterop' in tsconfig for correct import resolution.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"search_vec":"'arbitrari':34 'base':90 'chang':41,52,85 'collect':46 'custom':37 'data':17,31,35 'defin':14 'diff':56,89 'diff-bas':88 'differenti':63 'ecosystem':68 'entri':82 'fetch':38 'framework':12 'handl':20 'includ':98 'increment':91 'insit':1,11,67,70,73,100 'insite-users-server-w':72 'insite-w':69 'integr':23,65 'javascript':99 'key':62 'layer':8 'level':79 'low':78 'low-level':77 'manual':40 'map':44,94 'mode':32,95 'mongodb':45,84 'name':16 'notif':42 'npm':61 'object':33 'point':83 'pub/sub':7 'public':15,102 'publish':58 'query/projection/sort':48 'react':50 'real':26 'real-tim':25 'send':55 'server':3,5,75,103 'server-sid':4 'side':6 'sourc':18 'stream':53,86 'subscript':2,19,101 'support':29,87 'tight':64 'time':27 'two':30 'type':97 'typescript':96,104 'updat':28,57,92 'user':74 'v2.4.0':13 'via':36 'websocket':22 'week':59 'ws':71,76,81","created_at":"2026-06-04T18:51:43.714614+00:00","updated_at":"2026-06-04T18:51:43.714614+00:00","problems":[{"fix":"Change to import statement: import { Publication } from 'insite-subscriptions-server'","cause":"Using require() on an ESM-only package (v2+).","error":"ERR_REQUIRE_ESM"},{"fix":"Update Node.js to >=20.0.0 and ensure package version is 2.x. Also verify tsconfig has proper moduleResolution.","cause":"Import path not recognized due to subpath exports misconfiguration or outdated Node.js.","error":"Cannot find module 'insite-subscriptions-server/ws'"},{"fix":"Use named import: import { Publication } from 'insite-subscriptions-server'","cause":"Default import instead of named import for Publication.","error":"TypeError: Publication is not a constructor"},{"fix":"Use the 'wss' exported from 'insite-subscriptions-server/ws' which extends WebSocketServer with publish().","cause":"Attempting to use wss.publish() on a plain WebSocketServer without insite-ws integration.","error":"Property 'publish' does not exist on type 'WebSocketServer'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/nesvet/insite#readme","github":"https://github.com/nesvet/insite","docs":null,"changelog":null,"pypi":null,"npm":"insite-subscriptions-server","openapi_spec":null,"status_page":null,"smithery":null,"categories":["messaging","database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-04","next_check":"2026-09-02","install_tag":null}}