@graphorin/client 0.6.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphorin/client",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Reference TypeScript client for the Graphorin standalone server. Wraps the WebSocket subprotocol `graphorin.protocol.v1` (with the optional Server-Sent Events fallback for proxy-restricted environments) behind an ergonomic `GraphorinClient` class: `connect()`, `subscribe({ target, id })` returning an async-iterable subscription, `cancel(runId, opts)`, `resume(runId, directive)`, `ping()`, `disconnect()`. Handles the browser ticket flow (single-use ticket attached as a `ticket.<value>` `Sec-WebSocket-Protocol` token), exponential-backoff reconnect with `lastEventId` resume against the server replay buffer, and Zod-validated frame parsing on both directions. Browser-friendly: zero Node-only dependencies; the only runtime dependencies are `@graphorin/protocol` and `zod`. Created and maintained by Oleksiy Stepurenko.",
   "license": "MIT",
   "author": "Oleksiy Stepurenko",
@@ -27,7 +27,7 @@
   ],
   "type": "module",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -36,35 +36,36 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "default": "./dist/index.js"
     },
     "./client": {
       "types": "./dist/graphorin-client.d.ts",
-      "import": "./dist/graphorin-client.js"
+      "default": "./dist/graphorin-client.js"
     },
     "./transport": {
       "types": "./dist/transport/index.d.ts",
-      "import": "./dist/transport/index.js"
+      "default": "./dist/transport/index.js"
     },
     "./reconnect": {
       "types": "./dist/reconnect.d.ts",
-      "import": "./dist/reconnect.js"
+      "default": "./dist/reconnect.js"
     },
     "./errors": {
       "types": "./dist/errors.d.ts",
-      "import": "./dist/errors.js"
+      "default": "./dist/errors.js"
     },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
   "dependencies": {
     "zod": "^3.25.0",
-    "@graphorin/protocol": "0.6.1"
+    "@graphorin/protocol": "0.7.0"
   },
   "publishConfig": {
     "access": "public",
@@ -73,9 +74,9 @@
   "devDependencies": {
     "@types/ws": "^8.18.1",
     "ws": "^8.20.1",
-    "@graphorin/security": "0.6.1",
-    "@graphorin/server": "0.6.1",
-    "@graphorin/store-sqlite": "0.6.1"
+    "@graphorin/security": "0.7.0",
+    "@graphorin/server": "0.7.0",
+    "@graphorin/store-sqlite": "0.7.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/errors.ts

@@ -0,0 +1,170 @@
+/**
+ * Typed error hierarchy surfaced by `@graphorin/client`. Every error
+ * class extends the JavaScript built-in `Error` and exposes a stable
+ * `kind` discriminator so consumers can pattern-match without
+ * relying on `instanceof` (which behaves badly across module-system
+ * boundaries when the package is dual-loaded).
+ *
+ * @packageDocumentation
+ */
+
+import { RPC_ERROR_CODES } from '@graphorin/protocol';
+
+/**
+ * IP-19: map a JSON-RPC error code from a server `RpcFailure` frame to the
+ * client's discriminated {@link GraphorinClientErrorKind}, so a rate-limited
+ * or scope-denied RPC is distinguishable from a genuine protocol violation.
+ */
+export function kindForRpcCode(code: number): GraphorinClientErrorKind {
+  switch (code) {
+    case RPC_ERROR_CODES.RATE_LIMITED:
+      return 'rate-limited';
+    case RPC_ERROR_CODES.SCOPE_DENIED:
+      return 'scope-denied';
+    case RPC_ERROR_CODES.AUTH_REQUIRED:
+    case RPC_ERROR_CODES.AUTH_INVALID:
+      return 'auth-failed';
+    case RPC_ERROR_CODES.RUN_NOT_FOUND:
+      return 'run-not-found';
+    case RPC_ERROR_CODES.SUBSCRIPTION_NOT_FOUND:
+      return 'subscription-not-found';
+    case RPC_ERROR_CODES.INTERNAL_ERROR:
+      return 'server-error';
+    default:
+      // INVALID_REQUEST / INVALID_PARAMS / METHOD_NOT_FOUND / PROTOCOL_VIOLATION
+      // and any unknown code stay a protocol violation.
+      return 'protocol-violation';
+  }
+}
+
+/**
+ * Discriminator union of every error kind raised by the client.
+ *
+ * @stable
+ */
+export type GraphorinClientErrorKind =
+  | 'client-not-connected'
+  | 'transport-failed'
+  | 'subprotocol-mismatch'
+  | 'auth-failed'
+  | 'protocol-violation'
+  | 'subscription-not-found'
+  // IP-19: discriminated RPC-failure kinds so callers can branch on the
+  // server's error class instead of pattern-matching the message string.
+  | 'rate-limited'
+  | 'scope-denied'
+  | 'run-not-found'
+  | 'server-error'
+  | 'aborted'
+  /**
+   * W-152: the per-subscription client buffer hit
+   * `subscriptionQueueLimit` because the `for await` consumer fell
+   * behind the event flow; the subscription is closed with this typed
+   * error instead of growing the heap or silently dropping frames.
+   */
+  | 'flow-overflow'
+  | 'invalid-server-frame';
+
+/**
+ * Base class for every error raised by `@graphorin/client`. Carries a
+ * stable {@link GraphorinClientErrorKind} discriminator and an
+ * optional `cause` chain.
+ *
+ * @stable
+ */
+export class GraphorinClientError extends Error {
+  readonly kind: GraphorinClientErrorKind;
+
+  constructor(kind: GraphorinClientErrorKind, message: string, options: ErrorOptions = {}) {
+    super(message, options);
+    this.kind = kind;
+    this.name = 'GraphorinClientError';
+  }
+}
+
+/** @stable */
+export class ClientNotConnectedError extends GraphorinClientError {
+  constructor(message = 'GraphorinClient is not connected. Call connect() first.') {
+    super('client-not-connected', message);
+    this.name = 'ClientNotConnectedError';
+  }
+}
+
+/** @stable */
+export class TransportFailedError extends GraphorinClientError {
+  readonly code: number | undefined;
+
+  constructor(message: string, options: ErrorOptions & { readonly code?: number } = {}) {
+    super('transport-failed', message, options);
+    this.name = 'TransportFailedError';
+    this.code = options.code;
+  }
+}
+
+/** @stable */
+export class SubprotocolMismatchError extends GraphorinClientError {
+  readonly expected: string;
+  readonly actual: string | null;
+
+  constructor(expected: string, actual: string | null) {
+    super(
+      'subprotocol-mismatch',
+      `Server selected subprotocol '${actual ?? '<none>'}'; expected '${expected}'.`,
+    );
+    this.name = 'SubprotocolMismatchError';
+    this.expected = expected;
+    this.actual = actual;
+  }
+}
+
+/** @stable */
+export class AuthFailedError extends GraphorinClientError {
+  constructor(message = 'Authentication failed. Re-mint a token or request a new ticket.') {
+    super('auth-failed', message);
+    this.name = 'AuthFailedError';
+  }
+}
+
+/** @stable */
+export class ProtocolViolationError extends GraphorinClientError {
+  constructor(message: string, options: ErrorOptions = {}) {
+    super('protocol-violation', message, options);
+    this.name = 'ProtocolViolationError';
+  }
+}
+
+/** @stable */
+export class SubscriptionNotFoundError extends GraphorinClientError {
+  readonly subscriptionId: string;
+
+  constructor(subscriptionId: string) {
+    super(
+      'subscription-not-found',
+      `Subscription '${subscriptionId}' is not active on this client.`,
+    );
+    this.name = 'SubscriptionNotFoundError';
+    this.subscriptionId = subscriptionId;
+  }
+}
+
+/** @stable */
+export class ClientAbortedError extends GraphorinClientError {
+  constructor(message = 'Operation aborted before completion.') {
+    super('aborted', message);
+    this.name = 'ClientAbortedError';
+  }
+}
+
+/** @stable */
+export class InvalidServerFrameError extends GraphorinClientError {
+  readonly issues: ReadonlyArray<{ path: ReadonlyArray<string | number>; message: string }>;
+
+  constructor(
+    message: string,
+    issues: ReadonlyArray<{ path: ReadonlyArray<string | number>; message: string }>,
+  ) {
+    super('invalid-server-frame', message);
+    this.name = 'InvalidServerFrameError';
+    this.issues = issues;
+  }
+}