@rvoh/psychic-websockets 0.2.4 → 0.3.1

package/dist/cjs/src/cable/index.js

@@ -6,7 +6,7 @@ const socketio = require("socket.io");
 const yoctocolors_1 = require("yoctocolors");
 const MissingWsRedisConnection_js_1 = require("../error/ws/MissingWsRedisConnection.js");
 const EnvInternal_js_1 = require("../helpers/EnvInternal.js");
-const index_js_1 = require("../psychic-application-websockets/index.js");
+const index_js_1 = require("../psychic-app-websockets/index.js");
 class Cable {
     app;
     io;
@@ -17,6 +17,12 @@ class Cable {
         this.app = app;
         this.config = config;
     }
+    /**
+     * @internal
+     *
+     * creates a new http server and binds it to a new socket.io server.
+     * this is automatically called when you call `start`.
+     */
     connect() {
         if (this.io)
             return;
@@ -25,6 +31,10 @@ class Cable {
         this.httpServer = psychic_1.PsychicServer.createPsychicHttpInstance(this.app, this.config.psychicApp.sslCredentials);
         this.io = new socketio.Server(this.httpServer, { cors: this.config.psychicApp.corsOptions });
     }
+    /**
+     * builds an http server and a socket.io server, binding to redis
+     * to enable redis pubsub, then starts the http server.
+     */
     async start(port) {
         this.connect();
         for (const hook of this.config.hooks.wsStart) {
@@ -62,6 +72,9 @@ class Cable {
             port: parseInt((port || psychicAppWebsockets.psychicApp.port).toString()),
         });
     }
+    /**
+     * stops the socket.io server, closing out of all redis connections
+     */
     async stop() {
         try {
             await this.io?.close();
@@ -78,6 +91,11 @@ class Cable {
             }
         }
     }
+    /**
+     * @internal
+     *
+     * stops the socket.io server, closing out of all redis connections
+     */
     async listen({ port }) {
         return new Promise(accept => {
             this.httpServer.listen(port, () => {
@@ -93,6 +111,11 @@ class Cable {
             });
         });
     }
+    /**
+     * @internal
+     *
+     * establishes redis pubsub mechanisms
+     */
     bindToRedis() {
         const pubClient = this.config.websocketOptions.connection;
         const subClient = this.config.websocketOptions.subConnection;

package/dist/cjs/src/cable/ws.js

@@ -1,18 +1,61 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InvalidWsPathError = void 0;
 const dream_1 = require("@rvoh/dream");
 const redis_emitter_1 = require("@socket.io/redis-emitter");
 const EnvInternal_js_1 = require("../helpers/EnvInternal.js");
-const index_js_1 = require("../psychic-application-websockets/index.js");
+const index_js_1 = require("../psychic-app-websockets/index.js");
 const redisWsKey_js_1 = require("./redisWsKey.js");
+const InvalidWsPathError_js_1 = require("../error/ws/InvalidWsPathError.js");
 class Ws {
     allowedPaths;
+    /**
+     * @internal
+     *
+     * the socket.io redis emitter instance, used to emit
+     * messages through redis to distributed websocket clusters
+     */
     io;
+    /**
+     * @internal
+     *
+     * the redis client used to bind socket.io to the redis emitter
+     */
     redisClient;
+    /**
+     * @internal
+     *
+     * the redis client used to bind socket.io to the redis emitter
+     */
     booted = false;
+    /**
+     * @internal
+     *
+     * the namespace used when connecting socket.io
+     * this will default to '/' if it is not provided
+     */
     namespace;
+    /**
+     * @internal
+     *
+     * when registering your application's users with psychic-websockets,
+     * you need to provide the following:
+     *   1. an identifier for your user (i.e. user.id)
+     *   2. a redisKeyPrefix, which is used to prefix your id before storing it in redis
+     *
+     * this enables you to have multiple namespaces in redis to safely store ids,
+     * i.e.
+     *
+     *  `user:1`
+     *  `admin-user:1`
+     */
     redisKeyPrefix;
+    /**
+     * call this method to bind a socket to a particular identifier
+     *
+     * @param socket - the socket.io socket instance
+     * @param id - the identifier you wish to bind to this socket instance
+     * @param redisKeyPrefix - (optional) the prefix you wish to use to couple to this id (defaults to 'user')
+     */
     static async register(socket, id, redisKeyPrefix = 'user') {
         const psychicWebsocketsApp = index_js_1.default.getOrFail();
         const redisClient = psychicWebsocketsApp.websocketOptions.connection;
@@ -37,11 +80,34 @@ class Ws {
             message: 'Successfully connected to psychic websockets',
         });
     }
-    constructor(allowedPaths, { namespace = '/', redisKeyPrefix = 'user', } = {}) {
+    constructor(allowedPaths, { 
+    /**
+     * the namespace used when connecting socket.io
+     * this will default to '/' if it is not provided
+     */
+    namespace = '/', 
+    /**
+     * when registering your application's users with psychic-websockets,
+     * you need to provide the following:
+     *   1. an identifier for your user (i.e. user.id)
+     *   2. a redisKeyPrefix, which is used to prefix your id before storing it in redis
+     *
+     * this enables you to have multiple namespaces in redis to safely store ids,
+     * i.e.
+     *
+     *  `user:1`
+     *  `admin-user:1`
+     */
+    redisKeyPrefix = 'user', } = {}) {
         this.allowedPaths = allowedPaths;
         this.namespace = namespace;
         this.redisKeyPrefix = redisKeyPrefix;
     }
+    /**
+     * @internal
+     *
+     * establishes a new socket.io-redis emitter
+     */
     boot() {
         if (this.booted)
             return;
@@ -50,36 +116,41 @@ class Ws {
         this.io = new redis_emitter_1.Emitter(this.redisClient).of(this.namespace);
         this.booted = true;
     }
+    /**
+     * emits data to the requested id (or dream instance) and path
+     *
+     * ```ts
+     * await ws.emit(123, '/ops/howyadoin', { hello: 'world' })
+     * ```
+     */
     async emit(id, path, 
     // eslint-disable-next-line
     data = {}) {
         if (this.allowedPaths.length && !this.allowedPaths.includes(path))
-            throw new InvalidWsPathError(path);
+            throw new InvalidWsPathError_js_1.default(path);
         this.boot();
         const socketIds = await this.findSocketIds(id?.isDreamInstance ? id.primaryKeyValue : id);
         for (const socketId of socketIds) {
             this.io.to(socketId).emit(path, data);
         }
     }
+    /**
+     * @internal
+     *
+     * used to find a redis key matching the id
+     */
     async findSocketIds(id) {
         this.boot();
         return (0, dream_1.uniq)(await this.redisClient.lrange(this.redisKey(id), 0, -1));
     }
+    /**
+     * @internal
+     *
+     * builds a redis key using the provided identifier and the redisKeyPrefix provided
+     * when this Ws instance was constructed.
+     */
     redisKey(userId) {
         return (0, redisWsKey_js_1.default)(userId, this.redisKeyPrefix);
     }
 }
 exports.default = Ws;
-class InvalidWsPathError extends Error {
-    invalidPath;
-    constructor(invalidPath) {
-        super();
-        this.invalidPath = invalidPath;
-    }
-    get message() {
-        return `
-      Invalid path passed to Ws: "${this.invalidPath}"
-    `;
-    }
-}
-exports.InvalidWsPathError = InvalidWsPathError;

package/dist/cjs/src/error/ws/InvalidWsPathError.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+class InvalidWsPathError extends Error {
+    invalidPath;
+    constructor(invalidPath) {
+        super();
+        this.invalidPath = invalidPath;
+    }
+    get message() {
+        return `
+      Invalid path passed to Ws: "${this.invalidPath}"
+    `;
+    }
+}
+exports.default = InvalidWsPathError;

package/dist/cjs/src/error/ws/MissingWsRedisConnection.js

@@ -11,7 +11,7 @@ In conf/app.ts, either:
   1.) disable websockets by omitting the call to psy.set('websockets', ...), OR
   2.) provide a redis connection for your websockets, as shown below:
 
-export default async (psy: PsychicApplication) => {
+export default async (psy: PsychicApp) => {
   ...
 
   psy.set('websockets', {

package/dist/cjs/src/index.js

@@ -1,9 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Ws = exports.Cable = exports.PsychicApplicationWebsockets = void 0;
-var index_js_1 = require("./psychic-application-websockets/index.js");
-Object.defineProperty(exports, "PsychicApplicationWebsockets", { enumerable: true, get: function () { return index_js_1.default; } });
-var index_js_2 = require("./cable/index.js");
-Object.defineProperty(exports, "Cable", { enumerable: true, get: function () { return index_js_2.default; } });
+exports.PsychicAppWebsockets = exports.Ws = exports.Cable = void 0;
+var index_js_1 = require("./cable/index.js");
+Object.defineProperty(exports, "Cable", { enumerable: true, get: function () { return index_js_1.default; } });
 var ws_js_1 = require("./cable/ws.js");
 Object.defineProperty(exports, "Ws", { enumerable: true, get: function () { return ws_js_1.default; } });
+var index_js_2 = require("./psychic-app-websockets/index.js");
+Object.defineProperty(exports, "PsychicAppWebsockets", { enumerable: true, get: function () { return index_js_2.default; } });

package/dist/cjs/src/psychic-app-websockets/cache.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cachePsychicAppWebsockets = cachePsychicAppWebsockets;
+exports.getCachedPsychicAppWebsockets = getCachedPsychicAppWebsockets;
+exports.getCachedPsychicAppWebsocketsOrFail = getCachedPsychicAppWebsocketsOrFail;
+let _psychicAppWebsockets = undefined;
+function cachePsychicAppWebsockets(psychicAppWebsockets) {
+    _psychicAppWebsockets = psychicAppWebsockets;
+}
+function getCachedPsychicAppWebsockets() {
+    return _psychicAppWebsockets;
+}
+function getCachedPsychicAppWebsocketsOrFail() {
+    if (!_psychicAppWebsockets)
+        throw new Error('must call `cachePsychicAppWebsockets` before loading cached psychic application websockets');
+    return _psychicAppWebsockets;
+}

package/dist/cjs/src/{psychic-application-websockets → psychic-app-websockets}/index.js

@@ -2,9 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const index_js_1 = require("../cable/index.js");
 const cache_js_1 = require("./cache.js");
-class PsychicApplicationWebsockets {
+class PsychicAppWebsockets {
     static async init(psychicApp, cb) {
-        const psychicWsApp = new PsychicApplicationWebsockets(psychicApp);
+        const psychicWsApp = new PsychicAppWebsockets(psychicApp);
         await cb(psychicWsApp);
         psychicApp.on('server:shutdown', async (psychicServer) => {
             const cable = psychicServer.$attached.cable;
@@ -20,17 +20,17 @@ class PsychicApplicationWebsockets {
             psychicServer.attach('cable', cable);
             return cable.httpServer;
         });
-        (0, cache_js_1.cachePsychicApplicationWebsockets)(psychicWsApp);
+        (0, cache_js_1.cachePsychicAppWebsockets)(psychicWsApp);
         return psychicWsApp;
     }
     /**
      * Returns the cached psychic application if it has been set.
      * If it has not been set, an exception is raised.
      *
-     * The psychic application can be set by calling PsychicApplication#init
+     * The psychic application can be set by calling PsychicApp#init
      */
     static getOrFail() {
-        return (0, cache_js_1.getCachedPsychicApplicationWebsocketsOrFail)();
+        return (0, cache_js_1.getCachedPsychicAppWebsocketsOrFail)();
     }
     psychicApp;
     static log(...args) {
@@ -61,7 +61,7 @@ class PsychicApplicationWebsockets {
                 this._hooks.wsConnect.push(cb);
                 break;
             default:
-                throw new Error(`unrecognized event provided to PsychicApplicationWebsockets#on: ${hookEventType}`);
+                throw new Error(`unrecognized event provided to PsychicAppWebsockets#on: ${hookEventType}`);
         }
     }
     set(option, value) {
@@ -79,8 +79,8 @@ class PsychicApplicationWebsockets {
                 };
                 break;
             default:
-                throw new Error(`Unhandled option type passed to PsychicApplicationWebsockets#set: ${option}`);
+                throw new Error(`Unhandled option type passed to PsychicAppWebsockets#set: ${option}`);
         }
     }
 }
-exports.default = PsychicApplicationWebsockets;
+exports.default = PsychicAppWebsockets;

package/dist/esm/src/cable/index.js

@@ -4,7 +4,7 @@ import * as socketio from 'socket.io';
 import colors from 'yoctocolors';
 import MissingWsRedisConnection from '../error/ws/MissingWsRedisConnection.js';
 import EnvInternal from '../helpers/EnvInternal.js';
-import PsychicApplicationWebsockets from '../psychic-application-websockets/index.js';
+import PsychicAppWebsockets from '../psychic-app-websockets/index.js';
 export default class Cable {
     app;
     io;
@@ -15,6 +15,12 @@ export default class Cable {
         this.app = app;
         this.config = config;
     }
+    /**
+     * @internal
+     *
+     * creates a new http server and binds it to a new socket.io server.
+     * this is automatically called when you call `start`.
+     */
     connect() {
         if (this.io)
             return;
@@ -23,6 +29,10 @@ export default class Cable {
         this.httpServer = PsychicServer.createPsychicHttpInstance(this.app, this.config.psychicApp.sslCredentials);
         this.io = new socketio.Server(this.httpServer, { cors: this.config.psychicApp.corsOptions });
     }
+    /**
+     * builds an http server and a socket.io server, binding to redis
+     * to enable redis pubsub, then starts the http server.
+     */
     async start(port) {
         this.connect();
         for (const hook of this.config.hooks.wsStart) {
@@ -55,11 +65,14 @@ export default class Cable {
             }
         });
         this.bindToRedis();
-        const psychicAppWebsockets = PsychicApplicationWebsockets.getOrFail();
+        const psychicAppWebsockets = PsychicAppWebsockets.getOrFail();
         await this.listen({
             port: parseInt((port || psychicAppWebsockets.psychicApp.port).toString()),
         });
     }
+    /**
+     * stops the socket.io server, closing out of all redis connections
+     */
     async stop() {
         try {
             await this.io?.close();
@@ -76,11 +89,16 @@ export default class Cable {
             }
         }
     }
+    /**
+     * @internal
+     *
+     * stops the socket.io server, closing out of all redis connections
+     */
     async listen({ port }) {
         return new Promise(accept => {
             this.httpServer.listen(port, () => {
                 if (!EnvInternal.isTest) {
-                    const app = PsychicApplicationWebsockets.getOrFail().psychicApp;
+                    const app = PsychicAppWebsockets.getOrFail().psychicApp;
                     app.logger.info(PsychicServer.asciiLogo());
                     app.logger.info('\n');
                     app.logger.info(colors.cyan('socket server started                                      '));
@@ -91,6 +109,11 @@ export default class Cable {
             });
         });
     }
+    /**
+     * @internal
+     *
+     * establishes redis pubsub mechanisms
+     */
     bindToRedis() {
         const pubClient = this.config.websocketOptions.connection;
         const subClient = this.config.websocketOptions.subConnection;
@@ -99,16 +122,16 @@ export default class Cable {
         this.redisConnections.push(pubClient);
         this.redisConnections.push(subClient);
         pubClient.on('error', error => {
-            PsychicApplicationWebsockets.log('PUB CLIENT ERROR', error);
+            PsychicAppWebsockets.log('PUB CLIENT ERROR', error);
         });
         subClient.on('error', error => {
-            PsychicApplicationWebsockets.log('sub CLIENT ERROR', error);
+            PsychicAppWebsockets.log('sub CLIENT ERROR', error);
         });
         try {
             this.io.adapter(createAdapter(pubClient, subClient));
         }
         catch (error) {
-            PsychicApplicationWebsockets.log('FAILED TO ADAPT', error);
+            PsychicAppWebsockets.log('FAILED TO ADAPT', error);
         }
     }
 }

package/dist/esm/src/cable/ws.js

@@ -1,17 +1,61 @@
 import { DateTime, uniq } from '@rvoh/dream';
 import { Emitter } from '@socket.io/redis-emitter';
 import EnvInternal from '../helpers/EnvInternal.js';
-import PsychicApplicationWebsockets from '../psychic-application-websockets/index.js';
+import PsychicAppWebsockets from '../psychic-app-websockets/index.js';
 import redisWsKey from './redisWsKey.js';
+import InvalidWsPathError from '../error/ws/InvalidWsPathError.js';
 export default class Ws {
     allowedPaths;
+    /**
+     * @internal
+     *
+     * the socket.io redis emitter instance, used to emit
+     * messages through redis to distributed websocket clusters
+     */
     io;
+    /**
+     * @internal
+     *
+     * the redis client used to bind socket.io to the redis emitter
+     */
     redisClient;
+    /**
+     * @internal
+     *
+     * the redis client used to bind socket.io to the redis emitter
+     */
     booted = false;
+    /**
+     * @internal
+     *
+     * the namespace used when connecting socket.io
+     * this will default to '/' if it is not provided
+     */
     namespace;
+    /**
+     * @internal
+     *
+     * when registering your application's users with psychic-websockets,
+     * you need to provide the following:
+     *   1. an identifier for your user (i.e. user.id)
+     *   2. a redisKeyPrefix, which is used to prefix your id before storing it in redis
+     *
+     * this enables you to have multiple namespaces in redis to safely store ids,
+     * i.e.
+     *
+     *  `user:1`
+     *  `admin-user:1`
+     */
     redisKeyPrefix;
+    /**
+     * call this method to bind a socket to a particular identifier
+     *
+     * @param socket - the socket.io socket instance
+     * @param id - the identifier you wish to bind to this socket instance
+     * @param redisKeyPrefix - (optional) the prefix you wish to use to couple to this id (defaults to 'user')
+     */
     static async register(socket, id, redisKeyPrefix = 'user') {
-        const psychicWebsocketsApp = PsychicApplicationWebsockets.getOrFail();
+        const psychicWebsocketsApp = PsychicAppWebsockets.getOrFail();
         const redisClient = psychicWebsocketsApp.websocketOptions.connection;
         const interpretedId = id?.isDreamInstance ? id.primaryKeyValue : id;
         const key = redisWsKey(interpretedId, redisKeyPrefix);
@@ -34,19 +78,49 @@ export default class Ws {
             message: 'Successfully connected to psychic websockets',
         });
     }
-    constructor(allowedPaths, { namespace = '/', redisKeyPrefix = 'user', } = {}) {
+    constructor(allowedPaths, { 
+    /**
+     * the namespace used when connecting socket.io
+     * this will default to '/' if it is not provided
+     */
+    namespace = '/', 
+    /**
+     * when registering your application's users with psychic-websockets,
+     * you need to provide the following:
+     *   1. an identifier for your user (i.e. user.id)
+     *   2. a redisKeyPrefix, which is used to prefix your id before storing it in redis
+     *
+     * this enables you to have multiple namespaces in redis to safely store ids,
+     * i.e.
+     *
+     *  `user:1`
+     *  `admin-user:1`
+     */
+    redisKeyPrefix = 'user', } = {}) {
         this.allowedPaths = allowedPaths;
         this.namespace = namespace;
         this.redisKeyPrefix = redisKeyPrefix;
     }
+    /**
+     * @internal
+     *
+     * establishes a new socket.io-redis emitter
+     */
     boot() {
         if (this.booted)
             return;
-        const psychicWebsocketsApp = PsychicApplicationWebsockets.getOrFail();
+        const psychicWebsocketsApp = PsychicAppWebsockets.getOrFail();
         this.redisClient = psychicWebsocketsApp.websocketOptions.connection;
         this.io = new Emitter(this.redisClient).of(this.namespace);
         this.booted = true;
     }
+    /**
+     * emits data to the requested id (or dream instance) and path
+     *
+     * ```ts
+     * await ws.emit(123, '/ops/howyadoin', { hello: 'world' })
+     * ```
+     */
     async emit(id, path, 
     // eslint-disable-next-line
     data = {}) {
@@ -58,23 +132,22 @@ export default class Ws {
             this.io.to(socketId).emit(path, data);
         }
     }
+    /**
+     * @internal
+     *
+     * used to find a redis key matching the id
+     */
     async findSocketIds(id) {
         this.boot();
         return uniq(await this.redisClient.lrange(this.redisKey(id), 0, -1));
     }
+    /**
+     * @internal
+     *
+     * builds a redis key using the provided identifier and the redisKeyPrefix provided
+     * when this Ws instance was constructed.
+     */
     redisKey(userId) {
         return redisWsKey(userId, this.redisKeyPrefix);
     }
 }
-export class InvalidWsPathError extends Error {
-    invalidPath;
-    constructor(invalidPath) {
-        super();
-        this.invalidPath = invalidPath;
-    }
-    get message() {
-        return `
-      Invalid path passed to Ws: "${this.invalidPath}"
-    `;
-    }
-}

package/dist/esm/src/error/ws/InvalidWsPathError.js

@@ -0,0 +1,12 @@
+export default class InvalidWsPathError extends Error {
+    invalidPath;
+    constructor(invalidPath) {
+        super();
+        this.invalidPath = invalidPath;
+    }
+    get message() {
+        return `
+      Invalid path passed to Ws: "${this.invalidPath}"
+    `;
+    }
+}

package/dist/esm/src/error/ws/MissingWsRedisConnection.js

@@ -9,7 +9,7 @@ In conf/app.ts, either:
   1.) disable websockets by omitting the call to psy.set('websockets', ...), OR
   2.) provide a redis connection for your websockets, as shown below:
 
-export default async (psy: PsychicApplication) => {
+export default async (psy: PsychicApp) => {
   ...
 
   psy.set('websockets', {

package/dist/esm/src/index.js

@@ -1,3 +1,3 @@
-export { default as PsychicApplicationWebsockets } from './psychic-application-websockets/index.js';
 export { default as Cable } from './cable/index.js';
 export { default as Ws } from './cable/ws.js';
+export { default as PsychicAppWebsockets } from './psychic-app-websockets/index.js';

package/dist/esm/src/psychic-app-websockets/cache.js

@@ -0,0 +1,12 @@
+let _psychicAppWebsockets = undefined;
+export function cachePsychicAppWebsockets(psychicAppWebsockets) {
+    _psychicAppWebsockets = psychicAppWebsockets;
+}
+export function getCachedPsychicAppWebsockets() {
+    return _psychicAppWebsockets;
+}
+export function getCachedPsychicAppWebsocketsOrFail() {
+    if (!_psychicAppWebsockets)
+        throw new Error('must call `cachePsychicAppWebsockets` before loading cached psychic application websockets');
+    return _psychicAppWebsockets;
+}

package/dist/esm/src/{psychic-application-websockets → psychic-app-websockets}/index.js

@@ -1,8 +1,8 @@
 import Cable from '../cable/index.js';
-import { cachePsychicApplicationWebsockets, getCachedPsychicApplicationWebsocketsOrFail } from './cache.js';
-export default class PsychicApplicationWebsockets {
+import { cachePsychicAppWebsockets, getCachedPsychicAppWebsocketsOrFail } from './cache.js';
+export default class PsychicAppWebsockets {
     static async init(psychicApp, cb) {
-        const psychicWsApp = new PsychicApplicationWebsockets(psychicApp);
+        const psychicWsApp = new PsychicAppWebsockets(psychicApp);
         await cb(psychicWsApp);
         psychicApp.on('server:shutdown', async (psychicServer) => {
             const cable = psychicServer.$attached.cable;
@@ -18,17 +18,17 @@ export default class PsychicApplicationWebsockets {
             psychicServer.attach('cable', cable);
             return cable.httpServer;
         });
-        cachePsychicApplicationWebsockets(psychicWsApp);
+        cachePsychicAppWebsockets(psychicWsApp);
         return psychicWsApp;
     }
     /**
      * Returns the cached psychic application if it has been set.
      * If it has not been set, an exception is raised.
      *
-     * The psychic application can be set by calling PsychicApplication#init
+     * The psychic application can be set by calling PsychicApp#init
      */
     static getOrFail() {
-        return getCachedPsychicApplicationWebsocketsOrFail();
+        return getCachedPsychicAppWebsocketsOrFail();
     }
     psychicApp;
     static log(...args) {
@@ -59,7 +59,7 @@ export default class PsychicApplicationWebsockets {
                 this._hooks.wsConnect.push(cb);
                 break;
             default:
-                throw new Error(`unrecognized event provided to PsychicApplicationWebsockets#on: ${hookEventType}`);
+                throw new Error(`unrecognized event provided to PsychicAppWebsockets#on: ${hookEventType}`);
         }
     }
     set(option, value) {
@@ -77,7 +77,7 @@ export default class PsychicApplicationWebsockets {
                 };
                 break;
             default:
-                throw new Error(`Unhandled option type passed to PsychicApplicationWebsockets#set: ${option}`);
+                throw new Error(`Unhandled option type passed to PsychicAppWebsockets#set: ${option}`);
         }
     }
 }

package/dist/types/src/cable/index.d.ts

@@ -1,19 +1,42 @@
-import { Application } from 'express';
+import { Express } from 'express';
 import * as http from 'http';
 import * as socketio from 'socket.io';
-import PsychicApplicationWebsockets from '../psychic-application-websockets/index.js';
+import PsychicAppWebsockets from '../psychic-app-websockets/index.js';
 export default class Cable {
-    app: Application;
+    app: Express;
     io: socketio.Server | undefined;
     httpServer: http.Server;
     private config;
     private redisConnections;
-    constructor(app: Application, config: PsychicApplicationWebsockets);
+    constructor(app: Express, config: PsychicAppWebsockets);
+    /**
+     * @internal
+     *
+     * creates a new http server and binds it to a new socket.io server.
+     * this is automatically called when you call `start`.
+     */
     connect(): void;
+    /**
+     * builds an http server and a socket.io server, binding to redis
+     * to enable redis pubsub, then starts the http server.
+     */
     start(port?: number): Promise<void>;
+    /**
+     * stops the socket.io server, closing out of all redis connections
+     */
     stop(): Promise<void>;
+    /**
+     * @internal
+     *
+     * stops the socket.io server, closing out of all redis connections
+     */
     listen({ port }: {
         port: number | string;
     }): Promise<unknown>;
+    /**
+     * @internal
+     *
+     * establishes redis pubsub mechanisms
+     */
     bindToRedis(): void;
 }

package/dist/types/src/cable/ws.d.ts

@@ -3,23 +3,102 @@ import { Emitter } from '@socket.io/redis-emitter';
 import { Socket } from 'socket.io';
 export default class Ws<AllowedPaths extends readonly string[]> {
     allowedPaths: AllowedPaths & readonly string[];
+    /**
+     * @internal
+     *
+     * the socket.io redis emitter instance, used to emit
+     * messages through redis to distributed websocket clusters
+     */
     io: Emitter;
+    /**
+     * @internal
+     *
+     * the redis client used to bind socket.io to the redis emitter
+     */
     private redisClient;
+    /**
+     * @internal
+     *
+     * the redis client used to bind socket.io to the redis emitter
+     */
     private booted;
+    /**
+     * @internal
+     *
+     * the namespace used when connecting socket.io
+     * this will default to '/' if it is not provided
+     */
     private namespace;
+    /**
+     * @internal
+     *
+     * when registering your application's users with psychic-websockets,
+     * you need to provide the following:
+     *   1. an identifier for your user (i.e. user.id)
+     *   2. a redisKeyPrefix, which is used to prefix your id before storing it in redis
+     *
+     * this enables you to have multiple namespaces in redis to safely store ids,
+     * i.e.
+     *
+     *  `user:1`
+     *  `admin-user:1`
+     */
     private redisKeyPrefix;
+    /**
+     * call this method to bind a socket to a particular identifier
+     *
+     * @param socket - the socket.io socket instance
+     * @param id - the identifier you wish to bind to this socket instance
+     * @param redisKeyPrefix - (optional) the prefix you wish to use to couple to this id (defaults to 'user')
+     */
     static register(socket: Socket, id: IdType | Dream, redisKeyPrefix?: string): Promise<void>;
-    constructor(allowedPaths: AllowedPaths & readonly string[], { namespace, redisKeyPrefix, }?: {
+    constructor(allowedPaths: AllowedPaths & readonly string[], { 
+    /**
+     * the namespace used when connecting socket.io
+     * this will default to '/' if it is not provided
+     */
+    namespace, 
+    /**
+     * when registering your application's users with psychic-websockets,
+     * you need to provide the following:
+     *   1. an identifier for your user (i.e. user.id)
+     *   2. a redisKeyPrefix, which is used to prefix your id before storing it in redis
+     *
+     * this enables you to have multiple namespaces in redis to safely store ids,
+     * i.e.
+     *
+     *  `user:1`
+     *  `admin-user:1`
+     */
+    redisKeyPrefix, }?: {
         namespace?: string;
         redisKeyPrefix?: string;
     });
+    /**
+     * @internal
+     *
+     * establishes a new socket.io-redis emitter
+     */
     boot(): void;
+    /**
+     * emits data to the requested id (or dream instance) and path
+     *
+     * ```ts
+     * await ws.emit(123, '/ops/howyadoin', { hello: 'world' })
+     * ```
+     */
     emit<T extends Ws<AllowedPaths>, const P extends AllowedPaths[number]>(this: T, id: IdType | Dream, path: P, data?: any): Promise<void>;
+    /**
+     * @internal
+     *
+     * used to find a redis key matching the id
+     */
     findSocketIds(id: IdType): Promise<string[]>;
+    /**
+     * @internal
+     *
+     * builds a redis key using the provided identifier and the redisKeyPrefix provided
+     * when this Ws instance was constructed.
+     */
     private redisKey;
 }
-export declare class InvalidWsPathError extends Error {
-    private invalidPath;
-    constructor(invalidPath: string);
-    get message(): string;
-}

package/dist/types/src/error/ws/InvalidWsPathError.d.ts

@@ -0,0 +1,5 @@
+export default class InvalidWsPathError extends Error {
+    private invalidPath;
+    constructor(invalidPath: string);
+    get message(): string;
+}

package/dist/types/src/index.d.ts

@@ -1,3 +1,3 @@
-export { default as PsychicApplicationWebsockets } from './psychic-application-websockets/index.js';
 export { default as Cable } from './cable/index.js';
 export { default as Ws } from './cable/ws.js';
+export { default as PsychicAppWebsockets } from './psychic-app-websockets/index.js';

package/dist/types/src/psychic-app-websockets/cache.d.ts

@@ -0,0 +1,4 @@
+import PsychicAppWebsockets from './index.js';
+export declare function cachePsychicAppWebsockets(psychicAppWebsockets: PsychicAppWebsockets): void;
+export declare function getCachedPsychicAppWebsockets(): PsychicAppWebsockets | undefined;
+export declare function getCachedPsychicAppWebsocketsOrFail(): PsychicAppWebsockets;

package/dist/types/src/{psychic-application-websockets → psychic-app-websockets}/index.d.ts

@@ -1,33 +1,33 @@
-import { PsychicApplication } from '@rvoh/psychic';
+import { PsychicApp } from '@rvoh/psychic';
 import { Cluster, Redis } from 'ioredis';
 import { Socket, Server as SocketServer } from 'socket.io';
-export default class PsychicApplicationWebsockets {
-    static init(psychicApp: PsychicApplication, cb: (app: PsychicApplicationWebsockets) => void | Promise<void>): Promise<PsychicApplicationWebsockets>;
+export default class PsychicAppWebsockets {
+    static init(psychicApp: PsychicApp, cb: (app: PsychicAppWebsockets) => void | Promise<void>): Promise<PsychicAppWebsockets>;
     /**
      * Returns the cached psychic application if it has been set.
      * If it has not been set, an exception is raised.
      *
-     * The psychic application can be set by calling PsychicApplication#init
+     * The psychic application can be set by calling PsychicApp#init
      */
-    static getOrFail(): PsychicApplicationWebsockets;
-    psychicApp: PsychicApplication;
-    static log(...args: Parameters<typeof PsychicApplication.log>): void;
-    constructor(psychicApp: PsychicApplication);
+    static getOrFail(): PsychicAppWebsockets;
+    psychicApp: PsychicApp;
+    static log(...args: Parameters<typeof PsychicApp.log>): void;
+    constructor(psychicApp: PsychicApp);
     private _websocketOptions;
     get websocketOptions(): PsychicWebsocketOptions & {
         subConnection?: RedisOrRedisClusterConnection;
     };
     private _hooks;
-    get hooks(): PsychicApplicationWebsocketsHooks;
+    get hooks(): PsychicAppWebsocketsHooks;
     on<T extends PsychicWebsocketsHookEventType>(hookEventType: T, cb: T extends 'ws:start' ? (server: SocketServer) => void | Promise<void> : T extends 'ws:connect' ? (socket: Socket) => void | Promise<void> : never): void;
-    set<Opt extends PsychicApplicationWebsocketsOption>(option: Opt, value: unknown): void;
+    set<Opt extends PsychicAppWebsocketsOption>(option: Opt, value: unknown): void;
 }
 interface PsychicWebsocketOptions {
     connection: Redis;
 }
-export type PsychicApplicationWebsocketsOption = 'websockets';
+export type PsychicAppWebsocketsOption = 'websockets';
 export type PsychicWebsocketsHookEventType = 'ws:start' | 'ws:connect';
-export interface PsychicApplicationWebsocketsHooks {
+export interface PsychicAppWebsocketsHooks {
     wsStart: ((server: SocketServer) => void | Promise<void>)[];
     wsConnect: ((socket: Socket) => void | Promise<void>)[];
 }

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@rvoh/psychic-websockets",
   "description": "Websocket system for Psychic applications",
-  "version": "0.2.4",
+  "version": "0.3.1",
   "author": "RVO Health",
   "repository": {
     "type": "git",
@@ -25,16 +25,16 @@
   "scripts": {
     "client": "yarn --cwd=./client start",
     "client:fspec": "BROWSER=none VITE_PSYCHIC_ENV=test yarn --cwd=./client start",
-    "psy": "NODE_ENV=${NODE_ENV:-test} yarn psyts",
-    "psyjs": "node ./dist/test-app/src/cli/index.js",
-    "psyts": "node --experimental-specifier-resolution=node --import ./bin/esm.js ./test-app/src/cli/index.ts",
+    "psy": "NODE_ENV=${NODE_ENV:-test} yarn psy:ts",
+    "psy:js": "node ./dist/test-app/src/cli/index.js",
+    "psy:ts": "tsx ./test-app/src/cli/index.ts",
     "build": "echo \"building cjs...\" && rm -rf dist && npx tsc -p ./tsconfig.cjs.build.json && echo \"building esm...\" && npx tsc -p ./tsconfig.esm.build.json",
     "uspec": "vitest --config ./spec/unit/vite.config.ts",
     "fspec": "vitest run --config=./spec/features/vite.config.ts",
     "fspec:hanging": "vitest run --config=./spec/features/vite.config.ts --reporter=hanging-process",
     "format": "yarn run prettier . --write",
     "lint": "yarn run eslint --no-warn-ignored \"src/**/*.ts\" && yarn run prettier . --check",
-    "dev": "NODE_ENV=development WORKER_COUNT=0 ts-node --transpile-only ./test-app/main.ts",
+    "dev": "NODE_ENV=development WORKER_COUNT=0 tsx ./test-app/main.ts",
     "prepack": "yarn build"
   },
   "peerDependencies": {
@@ -48,10 +48,10 @@
   },
   "devDependencies": {
     "@eslint/js": "=9.0.0",
-    "@rvoh/dream": "^0.35.0",
-    "@rvoh/dream-spec-helpers": "^0.2.0",
-    "@rvoh/psychic": "^0.28.3",
-    "@rvoh/psychic-spec-helpers": "^0.2.0",
+    "@rvoh/dream": "^0.39.0",
+    "@rvoh/dream-spec-helpers": "^0.2.4",
+    "@rvoh/psychic": "^0.31.0",
+    "@rvoh/psychic-spec-helpers": "^0.6.0",
     "@socket.io/redis-adapter": "^8.3.0",
     "@socket.io/redis-emitter": "^5.1.0",
     "@types/express": "^4",
@@ -72,8 +72,8 @@
     "socket.io-adapter": "^2.5.5",
     "socket.io-client": "^4.8.1",
     "supertest": "^7.0.0",
-    "ts-node": "^10.9.2",
     "tslib": "^2.7.0",
+    "tsx": "^4.19.3",
     "typedoc": "^0.26.6",
     "typescript": "^5.8.2",
     "typescript-eslint": "=7.18.0",
@@ -83,4 +83,4 @@
   "dependencies": {
     "yoctocolors": "^2.1.1"
   }
-}
+}

package/dist/cjs/src/psychic-application-websockets/cache.js

@@ -1,17 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.cachePsychicApplicationWebsockets = cachePsychicApplicationWebsockets;
-exports.getCachedPsychicApplicationWebsockets = getCachedPsychicApplicationWebsockets;
-exports.getCachedPsychicApplicationWebsocketsOrFail = getCachedPsychicApplicationWebsocketsOrFail;
-let _psychicAppWebsockets = undefined;
-function cachePsychicApplicationWebsockets(psychicAppWebsockets) {
-    _psychicAppWebsockets = psychicAppWebsockets;
-}
-function getCachedPsychicApplicationWebsockets() {
-    return _psychicAppWebsockets;
-}
-function getCachedPsychicApplicationWebsocketsOrFail() {
-    if (!_psychicAppWebsockets)
-        throw new Error('must call `cachePsychicApplicationWebsockets` before loading cached psychic application websockets');
-    return _psychicAppWebsockets;
-}

package/dist/esm/src/psychic-application-websockets/cache.js

@@ -1,12 +0,0 @@
-let _psychicAppWebsockets = undefined;
-export function cachePsychicApplicationWebsockets(psychicAppWebsockets) {
-    _psychicAppWebsockets = psychicAppWebsockets;
-}
-export function getCachedPsychicApplicationWebsockets() {
-    return _psychicAppWebsockets;
-}
-export function getCachedPsychicApplicationWebsocketsOrFail() {
-    if (!_psychicAppWebsockets)
-        throw new Error('must call `cachePsychicApplicationWebsockets` before loading cached psychic application websockets');
-    return _psychicAppWebsockets;
-}

package/dist/types/src/psychic-application-websockets/cache.d.ts

@@ -1,4 +0,0 @@
-import PsychicApplicationWebsockets from './index.js';
-export declare function cachePsychicApplicationWebsockets(psychicAppWebsockets: PsychicApplicationWebsockets): void;
-export declare function getCachedPsychicApplicationWebsockets(): PsychicApplicationWebsockets | undefined;
-export declare function getCachedPsychicApplicationWebsocketsOrFail(): PsychicApplicationWebsockets;