@erinjs/core 1.0.0

package/core/packages/ws/src/index.ts

@@ -0,0 +1,12 @@
+export {
+  WebSocketManager,
+  type WebSocketManagerOptions,
+  type WebSocketConstructor,
+} from './WebSocketManager.js';
+export {
+  WebSocketShard,
+  type WebSocketShardOptions,
+  type WebSocketLike,
+} from './WebSocketShard.js';
+export { getDefaultWebSocket, getDefaultWebSocketSync } from './utils/getWebSocket.js';
+export { GatewayCloseCodes } from './utils/constants.js';

package/core/packages/ws/src/utils/constants.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import { GatewayCloseCodes } from './constants.js';
+
+describe('GatewayCloseCodes', () => {
+  it('has standard WebSocket close codes', () => {
+    expect(GatewayCloseCodes.Normal).toBe(1000);
+    expect(GatewayCloseCodes.GoingAway).toBe(1001);
+    expect(GatewayCloseCodes.ProtocolError).toBe(1002);
+    expect(GatewayCloseCodes.UnsupportedData).toBe(1003);
+  });
+
+  it('has Fluxer-specific codes', () => {
+    expect(GatewayCloseCodes.NotAuthenticated).toBe(4003);
+    expect(GatewayCloseCodes.AuthenticationFailed).toBe(4004);
+    expect(GatewayCloseCodes.RateLimited).toBe(4008);
+    expect(GatewayCloseCodes.InvalidShard).toBe(4010);
+    expect(GatewayCloseCodes.AckBackpressure).toBe(4013);
+  });
+
+  it('has all expected keys', () => {
+    const expected = [
+      'Normal',
+      'GoingAway',
+      'ProtocolError',
+      'UnsupportedData',
+      'NoStatusReceived',
+      'AbnormalClosure',
+      'UnknownError',
+      'UnknownOpcode',
+      'DecodeError',
+      'NotAuthenticated',
+      'AuthenticationFailed',
+      'AlreadyAuthenticated',
+      'InvalidSeq',
+      'RateLimited',
+      'SessionTimeout',
+      'InvalidShard',
+      'ShardingRequired',
+      'InvalidAPIVersion',
+      'AckBackpressure',
+    ];
+    for (const key of expected) {
+      expect(GatewayCloseCodes).toHaveProperty(key);
+    }
+  });
+});

package/core/packages/ws/src/utils/constants.ts

@@ -0,0 +1,22 @@
+/** Fluxer gateway close codes (aligned with docs / fluxerapp/fluxer). */
+export const GatewayCloseCodes = {
+  Normal: 1000,
+  GoingAway: 1001,
+  ProtocolError: 1002,
+  UnsupportedData: 1003,
+  NoStatusReceived: 1005,
+  AbnormalClosure: 1006,
+  UnknownError: 4000,
+  UnknownOpcode: 4001,
+  DecodeError: 4002,
+  NotAuthenticated: 4003,
+  AuthenticationFailed: 4004,
+  AlreadyAuthenticated: 4005,
+  InvalidSeq: 4007,
+  RateLimited: 4008,
+  SessionTimeout: 4009,
+  InvalidShard: 4010,
+  ShardingRequired: 4011,
+  InvalidAPIVersion: 4012,
+  AckBackpressure: 4013,
+} as const;

package/core/packages/ws/src/utils/getWebSocket.ts

@@ -0,0 +1,55 @@
+/**
+ * Returns the WebSocket implementation to use.
+ * Uses global WebSocket (browser, Node 22+, Deno, Bun) when available;
+ * otherwise uses the bundled `ws` package (Node 18/20).
+ * Users never need to install ws themselves.
+ */
+
+import ws from 'ws';
+
+type WSConstructor = new (url: string) => {
+  send(data: string | ArrayBufferLike): void;
+  close(code?: number): void;
+  readyState: number;
+  addEventListener?(type: string, listener: (e: unknown) => void): void;
+  on?(event: string, cb: (data?: unknown) => void): void;
+};
+
+let cached: WSConstructor | null = null;
+
+export function getDefaultWebSocketSync(): WSConstructor {
+  if (cached) return cached;
+  if (typeof globalThis.WebSocket !== 'undefined') {
+    cached = globalThis.WebSocket as unknown as WSConstructor;
+    return cached;
+  }
+  if (typeof require === 'function') {
+    try {
+      cached = require('ws') as WSConstructor;
+      return cached;
+    } catch {
+      // fall through
+    }
+  }
+  throw new Error(
+    'No WebSocket implementation. Use Node 22+, or run with CommonJS. The "ws" package is bundled with @erinjs/ws.',
+  );
+}
+
+/** Async version for ESM where we need dynamic import('ws'). */
+export async function getDefaultWebSocket(): Promise<WSConstructor> {
+  if (cached) return cached;
+  if (typeof globalThis.WebSocket !== 'undefined') {
+    cached = globalThis.WebSocket as unknown as WSConstructor;
+    return cached;
+  }
+  if (typeof require === 'function') {
+    try {
+      cached = require('ws') as WSConstructor;
+      return cached;
+    } catch {
+      // continue
+    }
+  }
+  return ws;
+}

package/core/packages/ws/src/ws.d.ts

@@ -0,0 +1,10 @@
+declare module 'ws' {
+  class WebSocket {
+    constructor(url: string);
+    send(data: string | ArrayBufferLike): void;
+    close(code?: number): void;
+    readyState: number;
+    on(event: string, cb: (data?: unknown) => void): this;
+  }
+  export = WebSocket;
+}

package/core/packages/ws/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "noEmit": false
+  },
+  "include": ["src/**/*"]
+}

package/core/packages/ws/tsup.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['cjs', 'esm'],
+  dts: true,
+  splitting: false,
+  clean: true,
+});