{"id":17570,"library":"deepstream.io-client-js","title":"deepstream.io JavaScript Client","description":"The `deepstream.io-client-js` library is the official JavaScript client for connecting to a deepstream.io server, enabling real-time data synchronization, remote procedure calls (RPCs), and publish/subscribe messaging patterns. The current major stable version, `4.0.0`, brought significant advancements over previous versions. This includes a new binary protocol for improved efficiency, full TypeScript declaration files for enhanced developer experience, and a comprehensive shift to promise-based APIs, leveraging `async/await` for asynchronous operations. A key differentiator is its robust offline support, allowing data to be stored client-side using IndexedDB and synchronized upon reconnection. While a precise release cadence isn't explicitly defined, the jump to `v4.0.0` indicates active and substantial development. It's designed for high-performance, real-time applications, offering an opinionated, stateful data synchronization model that distinguishes it from simpler WebSocket libraries or REST-based solutions.","status":"active","version":"2.3.4","language":"javascript","source_language":"en","source_url":"https://github.com/deepstreamIO/deepstream.io-client-js","tags":["javascript","typescript"],"install":[{"cmd":"npm install deepstream.io-client-js","lang":"bash","label":"npm"},{"cmd":"yarn add deepstream.io-client-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add deepstream.io-client-js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"As per the official documentation and bundled types, the module itself is callable as the client factory function when imported as a namespace object.","symbol":"deepstream (factory function)","correct":"import * as deepstream from 'deepstream.io-client-js';"},{"note":"For CommonJS environments, the module's main export directly provides the client factory function. Do not attempt to destructure.","wrong":"const { deepstream } = require('deepstream.io-client-js');","symbol":"deepstream (factory function, CommonJS)","correct":"const deepstream = require('deepstream.io-client-js');"},{"note":"Use this interface for type-checking your deepstream client instances, providing type safety for record, event, and RPC interactions. Available since v4.0.0 with full typings.","wrong":"import { Client } from 'deepstream.io-client-js';","symbol":"DeepstreamClient (Type)","correct":"import { DeepstreamClient } from 'deepstream.io-client-js';"}],"quickstart":{"code":"import * as deepstream from 'deepstream.io-client-js';\n\nconst DEEPSTREAM_URL = process.env.DEEPSTREAM_URL ?? 'ws://localhost:6020'; // Use wss:// for secure connections\n\nconst client = deepstream(DEEPSTREAM_URL);\n\nclient.on('connectionStateChanged', (connectionState) => {\n  console.log(`Deepstream connection state: ${connectionState}`);\n  if (connectionState === 'CLOSED' || connectionState === 'ERROR') {\n    console.error('Deepstream connection issue. Please check server status and URL.');\n  }\n});\n\nclient.login({ username: 'testUser', password: 'password123' })\n  .then(() => {\n    console.log('Login successful!');\n\n    // Example: Working with a record\n    const userRecord = client.record.get('users/john-doe');\n    userRecord.subscribe((data) => {\n      console.log('User record updated:', data);\n    });\n    userRecord.set({ name: 'John Doe', email: 'john.doe@example.com', lastUpdated: Date.now() });\n\n    // Example: Publishing an event\n    client.event.emit('user-activity', { userId: 'john-doe', action: 'loggedIn' });\n\n  })\n  .catch((error) => {\n    console.error('Login failed:', error.message);\n  });\n\n// Keep the Node.js process alive for events/records to sync\n// Not necessary in a browser environment\nsetInterval(() => {}, 1000 * 60);","lang":"typescript","description":"This quickstart demonstrates how to connect to a deepstream.io server, handle connection state changes, perform a promise-based login, subscribe to and update a data record, and emit a real-time event."},"warnings":[{"fix":"Ensure your deepstream.io server is updated to a version compatible with `deepstream.io-client-js` v4.0.0+.","message":"Version 4.0.0 introduced a new, incompatible binary protocol. Upgrading the client to `v4.0.0` or later requires the deepstream.io server to also be running a compatible version (e.g., `v4.x` or newer) to establish a connection.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Refactor existing asynchronous code to use `.then()/.catch()` or `async/await` syntax for handling responses and errors. Consult the `v4.0.0` documentation for updated API signatures.","message":"With `v4.0.0`, nearly all asynchronous APIs (e.g., `login`, `record.get`, `event.emit`) were refactored to return Promises, aligning with modern JavaScript `async/await` patterns. Callback-based APIs from previous versions are largely deprecated or removed.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Review and update your client initialization configuration object, especially the `offlineEnabled` and `indexdb` properties, to match the `v4.0.0` specification for offline capabilities.","message":"The configuration structure for offline support, including `offlineEnabled`, `saveUpdatesOffline`, and `indexdb` options, was introduced or significantly revised in `v4.0.0`. Older client configurations for offline features will not be compatible.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Ensure `tsconfig.json` is correctly configured. If experiencing type resolution issues, verify the specified `typeRoots` path is accurate. In many cases, types may be automatically discovered without this explicit `typeRoots` entry, depending on your `compilerOptions.moduleResolution`.","message":"The README suggests an explicit `typeRoots` entry in `tsconfig.json` (`\"./node_modules/deepstream.io-client.js/src/client.d.ts\"`) for TypeScript types. While functional, this approach is less common in modern TypeScript setups, which typically discover types automatically. This explicit path can sometimes conflict with other type resolution strategies.","severity":"gotcha","affected_versions":">=2.1.4"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Verify that your deepstream.io server is running and reachable. Ensure the `deepstream` client factory is initialized with the correct WebSocket endpoint (e.g., `ws://localhost:6020` or `wss://your.domain:6020`). Check firewall rules if connecting remotely.","cause":"The deepstream.io server is not running, is inaccessible, or the client is attempting to connect to an incorrect WebSocket URL (e.g., wrong port, HTTP instead of WS/WSS).","error":"Error: CONNECTION_ERROR - Cannot connect to deepstream"},{"fix":"For CommonJS, use `const deepstream = require('deepstream.io-client-js');`. For ES Modules, ensure you follow the pattern shown in the documentation: `import * as deepstream from 'deepstream.io-client-js';` then use `deepstream(...)`.","cause":"This error often occurs in CommonJS environments if the `deepstream` client factory function is incorrectly imported or treated as an object with named exports instead of a direct callable function.","error":"TypeError: deepstream(...) is not a function"},{"fix":"First, confirm `deepstream.io-client-js` is installed in your `node_modules`. Review your `tsconfig.json` for proper `compilerOptions` and ensure any explicit `typeRoots` or `include` paths are correct and point to the bundled type definitions (`src/client.d.ts`). Modern TypeScript setups often resolve types automatically if the package is installed.","cause":"The TypeScript compiler is unable to locate the type definition files for the package. This can happen if the package is not installed, `tsconfig.json` is misconfigured, or the explicit `typeRoots` path mentioned in the README is incorrect.","error":"TS2307: Cannot find module 'deepstream.io-client-js' or its corresponding type declarations."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}