@graphorin/client 0.6.0 → 0.7.0

package/dist/reconnect.js.map

@@ -1 +1 @@
-{"version":3,"file":"reconnect.js","names":[],"sources":["../src/reconnect.ts"],"sourcesContent":["/**\n * Pure-functional reconnect-backoff helper. Encapsulated in its own\n * module so the {@link GraphorinClient} stays free of timing\n * heuristics - and so tests can drive the policy with a deterministic\n * RNG.\n *\n * Algorithm: exponential backoff with full-jitter\n * (`delay = random(0, min(maxMs, baseMs * 2^attempt))`). The\n * implementation matches the AWS Architecture Blog \"exponential\n * backoff and jitter\" reference but is otherwise an original\n * formulation.\n *\n * @packageDocumentation\n */\n\n/**\n * Stable shape consumed by {@link computeBackoffMs}.\n *\n * @stable\n */\nexport interface BackoffPolicy {\n  /** Initial slot in milliseconds. Default `500`. */\n  readonly baseMs?: number;\n  /** Cap on every individual sleep. Default `30_000`. */\n  readonly maxMs?: number;\n  /**\n   * Hard cap on the number of attempts. The client surfaces a\n   * `TransportFailedError` once exceeded. Default `Infinity`.\n   */\n  readonly maxAttempts?: number;\n  /**\n   * Optional injection seam used by tests; defaults to `Math.random`.\n   */\n  readonly random?: () => number;\n}\n\n/**\n * Compute the number of milliseconds to sleep before the\n * `attempt`-th reconnect (1-indexed). Returns `null` when the policy\n * has been exhausted (`attempt > maxAttempts`).\n *\n * @stable\n */\nexport function computeBackoffMs(attempt: number, policy: BackoffPolicy = {}): number | null {\n  if (!Number.isFinite(attempt) || attempt < 1) {\n    throw new RangeError('computeBackoffMs: attempt must be a positive integer.');\n  }\n  const baseMs = policy.baseMs ?? 500;\n  const maxMs = policy.maxMs ?? 30_000;\n  const maxAttempts = policy.maxAttempts ?? Number.POSITIVE_INFINITY;\n  const random = policy.random ?? Math.random;\n  if (attempt > maxAttempts) return null;\n  // Exponential growth with full jitter, clamped to maxMs.\n  const exp = Math.min(maxMs, baseMs * 2 ** Math.min(attempt - 1, 30));\n  return Math.floor(random() * exp);\n}\n\n/**\n * Resolve when the requested number of milliseconds elapsed, or\n * reject (with a {@link DOMException}-style abort error) when the\n * supplied {@link AbortSignal} fires first.\n *\n * @stable\n */\nexport function sleep(durationMs: number, signal?: AbortSignal): Promise<void> {\n  if (signal?.aborted) {\n    return Promise.reject(abortError(signal.reason));\n  }\n  return new Promise<void>((resolve, reject) => {\n    const timeout = setTimeout(() => {\n      cleanup();\n      resolve();\n    }, durationMs);\n    const onAbort = (): void => {\n      cleanup();\n      reject(abortError(signal?.reason));\n    };\n    const cleanup = (): void => {\n      clearTimeout(timeout);\n      signal?.removeEventListener('abort', onAbort);\n    };\n    signal?.addEventListener('abort', onAbort, { once: true });\n  });\n}\n\nfunction abortError(reason: unknown): Error {\n  if (reason instanceof Error) return reason;\n  const err = new Error('Aborted.');\n  err.name = 'AbortError';\n  return err;\n}\n"],"mappings":";;;;;;;;AA2CA,SAAgB,iBAAiB,SAAiB,SAAwB,EAAE,EAAiB;AAC3F,KAAI,CAAC,OAAO,SAAS,QAAQ,IAAI,UAAU,EACzC,OAAM,IAAI,WAAW,wDAAwD;CAE/E,MAAM,SAAS,OAAO,UAAU;CAChC,MAAM,QAAQ,OAAO,SAAS;CAC9B,MAAM,cAAc,OAAO,eAAe,OAAO;CACjD,MAAM,SAAS,OAAO,UAAU,KAAK;AACrC,KAAI,UAAU,YAAa,QAAO;CAElC,MAAM,MAAM,KAAK,IAAI,OAAO,SAAS,KAAK,KAAK,IAAI,UAAU,GAAG,GAAG,CAAC;AACpE,QAAO,KAAK,MAAM,QAAQ,GAAG,IAAI;;;;;;;;;AAUnC,SAAgB,MAAM,YAAoB,QAAqC;AAC7E,KAAI,QAAQ,QACV,QAAO,QAAQ,OAAO,WAAW,OAAO,OAAO,CAAC;AAElD,QAAO,IAAI,SAAe,SAAS,WAAW;EAC5C,MAAM,UAAU,iBAAiB;AAC/B,YAAS;AACT,YAAS;KACR,WAAW;EACd,MAAM,gBAAsB;AAC1B,YAAS;AACT,UAAO,WAAW,QAAQ,OAAO,CAAC;;EAEpC,MAAM,gBAAsB;AAC1B,gBAAa,QAAQ;AACrB,WAAQ,oBAAoB,SAAS,QAAQ;;AAE/C,UAAQ,iBAAiB,SAAS,SAAS,EAAE,MAAM,MAAM,CAAC;GAC1D;;AAGJ,SAAS,WAAW,QAAwB;AAC1C,KAAI,kBAAkB,MAAO,QAAO;CACpC,MAAM,sBAAM,IAAI,MAAM,WAAW;AACjC,KAAI,OAAO;AACX,QAAO"}
+{"version":3,"file":"reconnect.js","names":[],"sources":["../src/reconnect.ts"],"sourcesContent":["/**\n * Pure-functional reconnect-backoff helper. Encapsulated in its own\n * module so the `GraphorinClient` stays free of timing\n * heuristics - and so tests can drive the policy with a deterministic\n * RNG.\n *\n * Algorithm: exponential backoff with full-jitter\n * (`delay = random(0, min(maxMs, baseMs * 2^attempt))`). The\n * implementation matches the AWS Architecture Blog \"exponential\n * backoff and jitter\" reference but is otherwise an original\n * formulation.\n *\n * @packageDocumentation\n */\n\n/**\n * Stable shape consumed by {@link computeBackoffMs}.\n *\n * @stable\n */\nexport interface BackoffPolicy {\n  /** Initial slot in milliseconds. Default `500`. */\n  readonly baseMs?: number;\n  /** Cap on every individual sleep. Default `30_000`. */\n  readonly maxMs?: number;\n  /**\n   * Hard cap on the number of attempts. The client surfaces a\n   * `TransportFailedError` once exceeded. Default `Infinity`.\n   */\n  readonly maxAttempts?: number;\n  /**\n   * Optional injection seam used by tests; defaults to `Math.random`.\n   */\n  readonly random?: () => number;\n}\n\n/**\n * Compute the number of milliseconds to sleep before the\n * `attempt`-th reconnect (1-indexed). Returns `null` when the policy\n * has been exhausted (`attempt > maxAttempts`).\n *\n * @stable\n */\nexport function computeBackoffMs(attempt: number, policy: BackoffPolicy = {}): number | null {\n  if (!Number.isFinite(attempt) || attempt < 1) {\n    throw new RangeError('computeBackoffMs: attempt must be a positive integer.');\n  }\n  const baseMs = policy.baseMs ?? 500;\n  const maxMs = policy.maxMs ?? 30_000;\n  const maxAttempts = policy.maxAttempts ?? Number.POSITIVE_INFINITY;\n  const random = policy.random ?? Math.random;\n  if (attempt > maxAttempts) return null;\n  // Exponential growth with full jitter, clamped to maxMs.\n  const exp = Math.min(maxMs, baseMs * 2 ** Math.min(attempt - 1, 30));\n  return Math.floor(random() * exp);\n}\n\n/**\n * Resolve when the requested number of milliseconds elapsed, or\n * reject (with a `DOMException`-style abort error) when the\n * supplied `AbortSignal` fires first.\n *\n * @stable\n */\nexport function sleep(durationMs: number, signal?: AbortSignal): Promise<void> {\n  if (signal?.aborted) {\n    return Promise.reject(abortError(signal.reason));\n  }\n  return new Promise<void>((resolve, reject) => {\n    const timeout = setTimeout(() => {\n      cleanup();\n      resolve();\n    }, durationMs);\n    const onAbort = (): void => {\n      cleanup();\n      reject(abortError(signal?.reason));\n    };\n    const cleanup = (): void => {\n      clearTimeout(timeout);\n      signal?.removeEventListener('abort', onAbort);\n    };\n    signal?.addEventListener('abort', onAbort, { once: true });\n  });\n}\n\nfunction abortError(reason: unknown): Error {\n  if (reason instanceof Error) return reason;\n  const err = new Error('Aborted.');\n  err.name = 'AbortError';\n  return err;\n}\n"],"mappings":";;;;;;;;AA2CA,SAAgB,iBAAiB,SAAiB,SAAwB,EAAE,EAAiB;AAC3F,KAAI,CAAC,OAAO,SAAS,QAAQ,IAAI,UAAU,EACzC,OAAM,IAAI,WAAW,wDAAwD;CAE/E,MAAM,SAAS,OAAO,UAAU;CAChC,MAAM,QAAQ,OAAO,SAAS;CAC9B,MAAM,cAAc,OAAO,eAAe,OAAO;CACjD,MAAM,SAAS,OAAO,UAAU,KAAK;AACrC,KAAI,UAAU,YAAa,QAAO;CAElC,MAAM,MAAM,KAAK,IAAI,OAAO,SAAS,KAAK,KAAK,IAAI,UAAU,GAAG,GAAG,CAAC;AACpE,QAAO,KAAK,MAAM,QAAQ,GAAG,IAAI;;;;;;;;;AAUnC,SAAgB,MAAM,YAAoB,QAAqC;AAC7E,KAAI,QAAQ,QACV,QAAO,QAAQ,OAAO,WAAW,OAAO,OAAO,CAAC;AAElD,QAAO,IAAI,SAAe,SAAS,WAAW;EAC5C,MAAM,UAAU,iBAAiB;AAC/B,YAAS;AACT,YAAS;KACR,WAAW;EACd,MAAM,gBAAsB;AAC1B,YAAS;AACT,UAAO,WAAW,QAAQ,OAAO,CAAC;;EAEpC,MAAM,gBAAsB;AAC1B,gBAAa,QAAQ;AACrB,WAAQ,oBAAoB,SAAS,QAAQ;;AAE/C,UAAQ,iBAAiB,SAAS,SAAS,EAAE,MAAM,MAAM,CAAC;GAC1D;;AAGJ,SAAS,WAAW,QAAwB;AAC1C,KAAI,kBAAkB,MAAO,QAAO;CACpC,MAAM,sBAAM,IAAI,MAAM,WAAW;AACjC,KAAI,OAAO;AACX,QAAO"}

package/dist/transport/types.d.ts

@@ -88,7 +88,7 @@ interface Transport {
    * Send a client → server frame. Throws when the transport is not
    * in the open state, or when the underlying back-end does not
    * support send (the SSE transport throws every send via
-   * {@link import('../errors.js').TransportFailedError} - clients
+   * `TransportFailedError` - clients
    * should fall back to REST for control-plane operations on SSE).
    */
   send(frame: ClientMessage): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphorin/client",
-  "version": "0.6.0",
+  "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.0"
+    "@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.0",
-    "@graphorin/server": "0.6.0",
-    "@graphorin/store-sqlite": "0.6.0"
+    "@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;
+  }
+}