@websimai/socket-types 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Roman A
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @websimai/socket-types
+
+WebsimSocket type declarations

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@websimai/socket-types",
+  "version": "0.0.1",
+  "description": "WebsimSocket type declarations",
+  "author": "GameRoMan",
+  "license": "MIT",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts"
+    },
+    "./socket": {
+      "types": "./src/socket.d.ts"
+    }
+  },
+  "scripts": {
+    "publish": "bun publish --access public"
+  },
+  "keywords": [
+    "websim",
+    "types",
+    "typescript"
+  ],
+  "peerDependencies": {
+    "typescript": "^5.9.2"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,15 @@
+import type { WebsimSocket as WebsimSocketClass } from "./socket";
+
+type WebsimSocketConstructor = typeof WebsimSocketClass;
+
+declare global {
+  interface Window {
+    readonly WebsimSocket: WebsimSocketConstructor;
+  }
+
+  const WebsimSocket: WebsimSocketConstructor;
+}
+
+type WebsimSocket = InstanceType<WebsimSocketConstructor>;
+
+export { WebsimSocket };

package/src/socket.d.ts

@@ -0,0 +1,271 @@
+type Expand<T> = T extends infer O ? { [K in keyof O]: O[K] } : never;
+
+type KeyValue = Record<string, any>;
+
+interface WebsimSocketParty {
+  /**
+   * Object containing the client ID, avatar URL, and username of this connected client.
+   */
+  client: {
+    id: string;
+    avatarUrl: `https://${string}`;
+    username: string;
+  };
+
+  /**
+   * Object containing all connected peers, including this client.
+   * This is always up-to-date.
+   */
+  peers: {
+    [id: string]: {
+      avatarUrl: `https://${string}`;
+      username: string;
+      id: string;
+      is_anonymous: boolean;
+    };
+  };
+
+  subscribe: (
+    callback: (peers: {
+      [clientId: string]: { avatarUrl: string; username: string };
+    }) => void
+  ) => () => void;
+
+  /**
+   * Object containing the current presence state of all connected peers, including this client.
+   * This is always up-to-date after initialization.
+   */
+  presence: KeyValue;
+
+  /**
+   * Updates the current client's presence state.
+   * @param presence The new presence state to set.
+   */
+  updatePresence<TPresence extends KeyValue>(presence: TPresence): void;
+
+  /**
+   * Subscribe to presence updates from all peers.
+   * @param callback Function to call when presence changes.
+   * @returns Function to unsubscribe.
+   */
+  subscribePresence<TPresence extends KeyValue>(
+    callback: (presence: { [clientId: string]: TPresence }) => void
+  ): () => void;
+
+  /**
+   * Object containing the current room-wide state.
+   * This is always up-to-date.
+   */
+  roomState: KeyValue;
+}
+
+interface CollectionAPI<T extends string> {
+  getList: <TData extends KeyValue>() => Promise<
+    Expand<
+      TData & {
+        id: string;
+        $type: T;
+        created_at: string;
+        updated_at: string;
+        user_id: string;
+        username: string;
+      }
+    >[]
+  >;
+  create: <TData extends KeyValue>(
+    data: TData
+  ) => Promise<
+    Expand<
+      TData & {
+        id: string;
+        $type: T;
+        created_at: string;
+        username: string;
+      }
+    >
+  >;
+  update: <T_Id extends string, TData extends KeyValue>(
+    id: T_Id,
+    data: TData
+  ) => Promise<
+    Expand<
+      TData & {
+        id: T_Id;
+        $type: T;
+        created_at: string;
+        username: string;
+      }
+    >
+  >;
+  upsert: <
+    TData extends KeyValue & { id?: T_Id },
+    T_Id extends string = string
+  >(
+    data: TData
+  ) => Promise<
+    Expand<
+      TData extends { id: T_Id }
+        ? TData &
+            KeyValue & {
+              id: T_Id;
+              $type: T;
+              created_at: string;
+              username: string;
+            }
+        : TData & {
+            id: T_Id;
+            $type: T;
+            created_at: string;
+            username: string;
+          }
+    >
+  >;
+  delete: (id: string) => Promise<void>;
+  subscribe: (
+    callback: (
+      records: Expand<
+        KeyValue & {
+          id: string;
+          $type: T;
+          created_at: string;
+          updated_at: string;
+          user_id: string;
+          username: string;
+        }
+      >[]
+    ) => void
+  ) => () => void;
+  filter: (filters: KeyValue) => CollectionAPI<T>;
+}
+
+interface QueryAPI<T extends readonly KeyValue[] = KeyValue[]>
+  extends PromiseLike<T> {
+  getList: () => Promise<T>;
+  subscribe: (callback: (records: T) => void) => () => void;
+}
+
+export class WebsimSocket {
+  constructor();
+
+  readonly CONNECTING: 0;
+  readonly OPEN: 1;
+  readonly CLOSING: 2;
+  readonly CLOSED: 3;
+
+  readonly binaryType: "arraybuffer" | (string & {});
+  readonly bufferedAmount: number;
+  readonly extensions: string;
+  readonly protocol: "ws" | "wss";
+  readonly readyState: 0 | 1 | 2 | 3;
+  readonly url: string;
+
+  accept(): void;
+  serializeAttachment(): void;
+  deserializeAttachment(): void;
+
+  onclose: ((this: WebSocket, ev: CloseEvent) => any) | null;
+  onerror: ((this: WebSocket, ev: Event) => any) | null;
+  onmessage: ((this: WebSocket, ev: MessageEvent) => any) | null;
+  onopen: ((this: WebSocket, ev: Event) => any) | null;
+
+  dispatchEvent(event: Event | MessageEvent | CloseEvent | ErrorEvent): boolean;
+
+  close(_code?: number, _reason?: string): void;
+  send<TData extends string | object>(data: TData): void;
+
+  query(queryString: string, params?: any[]): QueryAPI;
+
+  collection<T extends string>($type: T): CollectionAPI<T>;
+
+  clientId: string;
+
+  /**
+   * Object containing information about the connected client and their peers.
+   */
+  party: WebsimSocketParty;
+
+  /**
+   * Legacy event handler for changes in connected peers.
+   * @param peers An object with client IDs as keys, each containing the client's avatar URL and username.
+   */
+  onPeersChanged:
+    | ((peers: {
+        [clientId: string]: { avatarUrl: string; username: string };
+      }) => any)
+    | null;
+
+  /**
+   * Initialize the WebSocket connection.
+   * @returns A promise that resolves when initialization is complete.
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Request a presence update from a specific client.
+   * @param clientId The ID of the client to request an update from.
+   * @param update The update to request.
+   */
+  requestPresenceUpdate(clientId: string, update: KeyValue): void;
+
+  /**
+   * Subscribe to presence update requests from other clients.
+   * @param callback Function to call when a presence update is requested.
+   * @returns Function to unsubscribe.
+   */
+  subscribePresenceUpdateRequests<TUpdateRequest extends KeyValue>(
+    callback: (updateRequest: TUpdateRequest, fromClientId: string) => void
+  ): () => void;
+
+  /**
+   * Updates the room-wide state. This merges with existing state.
+   * @param delta The new state to merge with current room state.
+   */
+  updateRoomState<TDelta extends KeyValue>(delta: TDelta): void;
+
+  /**
+   * Subscribe to room state updates.
+   * @param callback Function to call when room state changes.
+   * @returns Function to unsubscribe.
+   */
+  subscribeRoomState<TRoomState extends KeyValue>(
+    callback: (state: TRoomState) => void
+  ): () => void;
+
+  /**
+   * Object containing the current presence state of all connected peers, including this client.
+   * This is always up-to-date after initialization.
+   */
+  presence: { [clientId: string]: KeyValue };
+
+  /**
+   * Object containing the current room-wide state.
+   * This is always up-to-date.
+   */
+  roomState: KeyValue;
+
+  /**
+   * Object containing all connected peers, including this client.
+   * This is always up-to-date.
+   */
+  peers: {
+    [clientId: string]: {
+      avatarUrl: string;
+      username: string;
+    };
+  };
+
+  /**
+   * Updates the current client's presence state.
+   * @param presence The new presence state to set.
+   */
+  updatePresence<TPresence extends KeyValue>(presence: TPresence): void;
+
+  /**
+   * Subscribe to presence updates from all peers.
+   * @param callback Function to call when presence changes.
+   * @returns Function to unsubscribe.
+   */
+  subscribePresence<TPresence extends KeyValue>(
+    callback: (presence: { [clientId: string]: TPresence }) => void
+  ): () => void;
+}

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext", "DOM"],
+    "target": "esnext",
+    "module": "preserve",
+    "moduleDetection": "force",
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+
+    // Max strictness
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "forceConsistentCasingInFileNames": true,
+    "verbatimModuleSyntax": true
+  }
+}