samyama-sdk 1.8.0 → 1.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,96 @@
1
+ # samyama-sdk — TypeScript SDK for the Samyama Graph Database
2
+
3
+ A typed HTTP client for [Samyama](https://github.com/samyama-ai/samyama-graph),
4
+ a property-graph database with a Cypher query engine.
5
+
6
+ This package is **remote only**: it talks to a running Samyama server over
7
+ HTTP. There is no embedded mode in TypeScript — for in-process use, see the
8
+ Python or Rust SDK.
9
+
10
+ > The npm package `samyama-sdk` and the Rust crate `samyama-sdk` share a name.
11
+ > They are separate artifacts from the same repository.
12
+
13
+ ## Install
14
+
15
+ ```bash
16
+ npm install samyama-sdk
17
+ ```
18
+
19
+ ESM only. Needs Node 18+ (it uses the global `fetch`, `AbortSignal.timeout`
20
+ and `AbortSignal.any`).
21
+
22
+ ## Connect
23
+
24
+ ```ts
25
+ import { SamyamaClient } from "samyama-sdk";
26
+
27
+ const client = new SamyamaClient({
28
+ url: "http://localhost:8080", // default
29
+ timeoutMs: 30000, // whole-request deadline, default 30000
30
+ maxRetries: 2, // retries on timeout/connection failure
31
+ retryBaseDelayMs: 100, // doubled each attempt
32
+ });
33
+ ```
34
+
35
+ Or the factory, when the URL is all you need:
36
+
37
+ ```ts
38
+ const client = SamyamaClient.connectHttp("http://localhost:8080");
39
+ ```
40
+
41
+ ## First query
42
+
43
+ ```ts
44
+ import { SamyamaClient } from "samyama-sdk";
45
+
46
+ const client = SamyamaClient.connectHttp("http://localhost:8080");
47
+
48
+ await client.query('CREATE (:Person {name: "Alice"})-[:KNOWS]->(:Person {name: "Bob"})');
49
+
50
+ const result = await client.queryReadonly(
51
+ "MATCH (a:Person)-[:KNOWS]->(b:Person) RETURN a.name, b.name",
52
+ );
53
+
54
+ console.log(result.columns); // ["a.name", "b.name"]
55
+ for (const row of result.records) {
56
+ console.log(row); // ["Alice", "Bob"]
57
+ }
58
+ ```
59
+
60
+ `query` is read-write, `queryReadonly` is read-only. Both take an optional
61
+ second argument `graph`, which defaults to `"default"`.
62
+
63
+ A `QueryResult` is `{ nodes, edges, columns, records }`.
64
+
65
+ ## Other methods
66
+
67
+ | Method | Returns |
68
+ |---|---|
69
+ | `explain(cypher, graph?)` | the plan, as text rows in `records` |
70
+ | `profile(cypher, graph?)` | the executed plan with timings |
71
+ | `status()` | `ServerStatus` |
72
+ | `healthy()` | `boolean` |
73
+ | `ping()` | `string` |
74
+ | `schema()` | `GraphSchema` — node types, edge types, indexes, constraints |
75
+ | `sample(options?)` | a sample subgraph |
76
+ | `listGraphs()` | `string[]` |
77
+ | `deleteGraph(graph?)` | `void` |
78
+ | `importCsv(...)` / `importJson(...)` | import results |
79
+
80
+ `HttpTransport` is exported too, for callers that want the raw request layer
81
+ with their own `AbortSignal`.
82
+
83
+ ## Build from source
84
+
85
+ ```bash
86
+ npm install && npm run build && npm test
87
+ ```
88
+
89
+ ## More
90
+
91
+ - [`docs/SDK_API_CLI_ARCHITECTURE.md`](https://github.com/samyama-ai/samyama-graph/blob/main/docs/SDK_API_CLI_ARCHITECTURE.md)
92
+ — how the SDKs, the HTTP API and the CLI fit together.
93
+ - [`sdk/README.md`](https://github.com/samyama-ai/samyama-graph/blob/main/sdk/README.md)
94
+ — the other two SDKs (Python, Rust).
95
+
96
+ Apache-2.0.
@@ -74,6 +74,14 @@ export declare class SamyamaClient {
74
74
  * @param nodes - Array of objects, each becoming a node
75
75
  */
76
76
  importJson(label: string, nodes: Record<string, unknown>[]): Promise<JsonImportResult>;
77
+ /**
78
+ * Does the server answer, and does it call itself healthy?
79
+ *
80
+ * Returns false rather than throwing: "is it up" is a question whose negative
81
+ * answer is not exceptional, and `ping()` below throws, which makes it
82
+ * awkward inside a readiness loop.
83
+ */
84
+ healthy(): Promise<boolean>;
77
85
  /** Ping the server */
78
86
  ping(): Promise<string>;
79
87
  }
@@ -26,7 +26,11 @@ const DEFAULT_URL = "http://localhost:8080";
26
26
  export class SamyamaClient {
27
27
  constructor(options) {
28
28
  const url = options?.url ?? DEFAULT_URL;
29
- this.http = new HttpTransport(url);
29
+ this.http = new HttpTransport(url, {
30
+ timeoutMs: options?.timeoutMs,
31
+ maxRetries: options?.maxRetries,
32
+ retryBaseDelayMs: options?.retryBaseDelayMs,
33
+ });
30
34
  }
31
35
  /**
32
36
  * Connect to a Samyama server via HTTP.
@@ -104,6 +108,16 @@ export class SamyamaClient {
104
108
  async importJson(label, nodes) {
105
109
  return this.http.importJson(label, nodes);
106
110
  }
111
+ /**
112
+ * Does the server answer, and does it call itself healthy?
113
+ *
114
+ * Returns false rather than throwing: "is it up" is a question whose negative
115
+ * answer is not exceptional, and `ping()` below throws, which makes it
116
+ * awkward inside a readiness loop.
117
+ */
118
+ async healthy() {
119
+ return this.http.healthy();
120
+ }
107
121
  /** Ping the server */
108
122
  async ping() {
109
123
  const s = await this.status();
@@ -1,24 +1,82 @@
1
1
  import type { QueryResult, ServerStatus, GraphSchema, CsvImportResult, JsonImportResult } from "./types.js";
2
+ /**
3
+ * How the transport treats the network (API-06).
4
+ *
5
+ * Every field has a default, and the defaults are the point. Every call used to
6
+ * be a bare `fetch` with no `signal`, and `fetch` has **no timeout**: a server
7
+ * that accepts the connection and then stops talking leaves the promise pending
8
+ * for as long as the process lives (samyama-graph#1326).
9
+ */
10
+ export interface ConnectionOptions {
11
+ /** Deadline for a whole request, in milliseconds. */
12
+ timeoutMs?: number;
13
+ /** How many times a retryable failure is retried. 0 disables retry. */
14
+ maxRetries?: number;
15
+ /**
16
+ * Delay before the first retry, doubled each attempt.
17
+ *
18
+ * Constant-delay retry is deliberately not what this does: it is what turns
19
+ * one slow server into a thundering herd of clients waking together.
20
+ */
21
+ retryBaseDelayMs?: number;
22
+ }
23
+ /** Per-call overrides. `signal` lets a caller cancel. */
24
+ export interface RequestOptions {
25
+ /** Caller's cancellation signal, combined with the timeout. */
26
+ signal?: AbortSignal;
27
+ /** Override the transport's timeout for this call. */
28
+ timeoutMs?: number;
29
+ }
2
30
  /**
3
31
  * HTTP transport for the Samyama SDK.
4
32
  * Uses the native `fetch` API (works in Node.js 18+ and browsers).
5
33
  */
6
34
  export declare class HttpTransport {
7
35
  private baseUrl;
8
- constructor(baseUrl: string);
36
+ private options;
37
+ constructor(baseUrl: string, options?: ConnectionOptions);
38
+ /** The settings this transport was built with. */
39
+ get connectionOptions(): Required<ConnectionOptions>;
40
+ /**
41
+ * Is this failure worth retrying?
42
+ *
43
+ * A timeout or a connection failure, and nothing else. An HTTP error is the
44
+ * server answering; repeating a request it has already refused achieves
45
+ * nothing, and blindly repeating a write is how one duplicate becomes
46
+ * several. A caller's own `AbortSignal` firing is never retried — the caller
47
+ * asked to stop.
48
+ */
49
+ private static retryable;
50
+ /**
51
+ * Every request goes through here.
52
+ *
53
+ * One place, not fifteen: the missing timeout was missing at six separate
54
+ * `fetch` call sites, so fixing one of them fixed one of them.
55
+ */
56
+ private request;
57
+ /** Throw the server's error message, or the status if it sent none. */
58
+ private static fail;
59
+ private json;
9
60
  /** Execute a Cypher query via POST /api/query */
10
- query(cypher: string, graph?: string): Promise<QueryResult>;
61
+ query(cypher: string, graph?: string, opts?: RequestOptions): Promise<QueryResult>;
11
62
  /** Get server status via GET /api/status */
12
- status(): Promise<ServerStatus>;
63
+ status(opts?: RequestOptions): Promise<ServerStatus>;
64
+ /**
65
+ * Health check: does the server answer, and does it call itself healthy?
66
+ *
67
+ * Returns false rather than throwing, because "is it up" is a question whose
68
+ * negative answer is not exceptional.
69
+ */
70
+ healthy(opts?: RequestOptions): Promise<boolean>;
13
71
  /** Get graph schema via GET /api/schema */
14
- schema(): Promise<GraphSchema>;
72
+ schema(opts?: RequestOptions): Promise<GraphSchema>;
15
73
  /** Generic POST request returning typed JSON response */
16
- post<T>(path: string, body: unknown): Promise<T>;
74
+ post<T>(path: string, body: unknown, opts?: RequestOptions): Promise<T>;
17
75
  /** Import nodes from CSV via POST /api/import/csv (multipart) */
18
76
  importCsv(csvContent: string, label: string, options?: {
19
77
  idColumn?: string;
20
78
  delimiter?: string;
21
- }): Promise<CsvImportResult>;
79
+ }, opts?: RequestOptions): Promise<CsvImportResult>;
22
80
  /** Import nodes from JSON via POST /api/import/json */
23
- importJson(label: string, nodes: Record<string, unknown>[]): Promise<JsonImportResult>;
81
+ importJson(label: string, nodes: Record<string, unknown>[], opts?: RequestOptions): Promise<JsonImportResult>;
24
82
  }
@@ -1,62 +1,123 @@
1
+ const DEFAULTS = {
2
+ timeoutMs: 30000,
3
+ maxRetries: 2,
4
+ retryBaseDelayMs: 100,
5
+ };
6
+ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
1
7
  /**
2
8
  * HTTP transport for the Samyama SDK.
3
9
  * Uses the native `fetch` API (works in Node.js 18+ and browsers).
4
10
  */
5
11
  export class HttpTransport {
6
- constructor(baseUrl) {
12
+ constructor(baseUrl, options = {}) {
7
13
  this.baseUrl = baseUrl.replace(/\/+$/, "");
14
+ this.options = { ...DEFAULTS, ...options };
15
+ }
16
+ /** The settings this transport was built with. */
17
+ get connectionOptions() {
18
+ return { ...this.options };
19
+ }
20
+ /**
21
+ * Is this failure worth retrying?
22
+ *
23
+ * A timeout or a connection failure, and nothing else. An HTTP error is the
24
+ * server answering; repeating a request it has already refused achieves
25
+ * nothing, and blindly repeating a write is how one duplicate becomes
26
+ * several. A caller's own `AbortSignal` firing is never retried — the caller
27
+ * asked to stop.
28
+ */
29
+ static retryable(err, callerSignal) {
30
+ if (callerSignal?.aborted)
31
+ return false;
32
+ if (err instanceof DOMException && err.name === "TimeoutError")
33
+ return true;
34
+ if (err instanceof DOMException && err.name === "AbortError")
35
+ return true;
36
+ return err instanceof TypeError; // fetch's network-failure shape
37
+ }
38
+ /**
39
+ * Every request goes through here.
40
+ *
41
+ * One place, not fifteen: the missing timeout was missing at six separate
42
+ * `fetch` call sites, so fixing one of them fixed one of them.
43
+ */
44
+ async request(path, init, opts = {}) {
45
+ const timeoutMs = opts.timeoutMs ?? this.options.timeoutMs;
46
+ let delay = this.options.retryBaseDelayMs;
47
+ for (let attempt = 0;; attempt++) {
48
+ // A fresh timeout per attempt, and the caller's signal combined with it,
49
+ // so cancellation wins over a retry that is still waiting.
50
+ const signals = [AbortSignal.timeout(timeoutMs)];
51
+ if (opts.signal)
52
+ signals.push(opts.signal);
53
+ const signal = signals.length === 1 ? signals[0] : AbortSignal.any(signals);
54
+ try {
55
+ return await fetch(`${this.baseUrl}${path}`, { ...init, signal });
56
+ }
57
+ catch (err) {
58
+ if (attempt >= this.options.maxRetries ||
59
+ !HttpTransport.retryable(err, opts.signal)) {
60
+ throw err;
61
+ }
62
+ await sleep(delay);
63
+ delay *= 2;
64
+ }
65
+ }
66
+ }
67
+ /** Throw the server's error message, or the status if it sent none. */
68
+ static async fail(response) {
69
+ const body = (await response.json().catch(() => ({
70
+ error: `HTTP ${response.status}`,
71
+ })));
72
+ throw new Error(body.error || `HTTP ${response.status}`);
73
+ }
74
+ async json(path, init, opts) {
75
+ const response = await this.request(path, init, opts);
76
+ if (!response.ok)
77
+ return HttpTransport.fail(response);
78
+ return (await response.json());
8
79
  }
9
80
  /** Execute a Cypher query via POST /api/query */
10
- async query(cypher, graph = "default") {
11
- const response = await fetch(`${this.baseUrl}/api/query`, {
81
+ async query(cypher, graph = "default", opts) {
82
+ return this.json("/api/query", {
12
83
  method: "POST",
13
84
  headers: { "Content-Type": "application/json" },
14
85
  body: JSON.stringify({ query: cypher, graph }),
15
- });
16
- if (!response.ok) {
17
- const body = (await response.json().catch(() => ({
18
- error: `HTTP ${response.status}`,
19
- })));
20
- throw new Error(body.error || `HTTP ${response.status}`);
21
- }
22
- return (await response.json());
86
+ }, opts);
23
87
  }
24
88
  /** Get server status via GET /api/status */
25
- async status() {
26
- const response = await fetch(`${this.baseUrl}/api/status`);
27
- if (!response.ok) {
28
- throw new Error(`Status endpoint returned ${response.status}`);
89
+ async status(opts) {
90
+ return this.json("/api/status", {}, opts);
91
+ }
92
+ /**
93
+ * Health check: does the server answer, and does it call itself healthy?
94
+ *
95
+ * Returns false rather than throwing, because "is it up" is a question whose
96
+ * negative answer is not exceptional.
97
+ */
98
+ async healthy(opts) {
99
+ try {
100
+ const s = await this.status(opts);
101
+ return s.status === "healthy";
102
+ }
103
+ catch {
104
+ return false;
29
105
  }
30
- return (await response.json());
31
106
  }
32
107
  /** Get graph schema via GET /api/schema */
33
- async schema() {
34
- const response = await fetch(`${this.baseUrl}/api/schema`);
35
- if (!response.ok) {
36
- const body = (await response.json().catch(() => ({
37
- error: `HTTP ${response.status}`,
38
- })));
39
- throw new Error(body.error || `HTTP ${response.status}`);
40
- }
41
- return (await response.json());
108
+ async schema(opts) {
109
+ return this.json("/api/schema", {}, opts);
42
110
  }
43
111
  /** Generic POST request returning typed JSON response */
44
- async post(path, body) {
45
- const response = await fetch(`${this.baseUrl}${path}`, {
112
+ async post(path, body, opts) {
113
+ return this.json(path, {
46
114
  method: "POST",
47
115
  headers: { "Content-Type": "application/json" },
48
116
  body: JSON.stringify(body),
49
- });
50
- if (!response.ok) {
51
- const err = (await response.json().catch(() => ({
52
- error: `HTTP ${response.status}`,
53
- })));
54
- throw new Error(err.error || `HTTP ${response.status}`);
55
- }
56
- return (await response.json());
117
+ }, opts);
57
118
  }
58
119
  /** Import nodes from CSV via POST /api/import/csv (multipart) */
59
- async importCsv(csvContent, label, options) {
120
+ async importCsv(csvContent, label, options, opts) {
60
121
  const formData = new FormData();
61
122
  const blob = new Blob([csvContent], { type: "text/csv" });
62
123
  formData.append("file", blob, "import.csv");
@@ -65,31 +126,14 @@ export class HttpTransport {
65
126
  formData.append("id_column", options.idColumn);
66
127
  if (options?.delimiter)
67
128
  formData.append("delimiter", options.delimiter);
68
- const response = await fetch(`${this.baseUrl}/api/import/csv`, {
69
- method: "POST",
70
- body: formData,
71
- });
72
- if (!response.ok) {
73
- const body = (await response.json().catch(() => ({
74
- error: `HTTP ${response.status}`,
75
- })));
76
- throw new Error(body.error || `HTTP ${response.status}`);
77
- }
78
- return (await response.json());
129
+ return this.json("/api/import/csv", { method: "POST", body: formData }, opts);
79
130
  }
80
131
  /** Import nodes from JSON via POST /api/import/json */
81
- async importJson(label, nodes) {
82
- const response = await fetch(`${this.baseUrl}/api/import/json`, {
132
+ async importJson(label, nodes, opts) {
133
+ return this.json("/api/import/json", {
83
134
  method: "POST",
84
135
  headers: { "Content-Type": "application/json" },
85
136
  body: JSON.stringify({ label, nodes }),
86
- });
87
- if (!response.ok) {
88
- const body = (await response.json().catch(() => ({
89
- error: `HTTP ${response.status}`,
90
- })));
91
- throw new Error(body.error || `HTTP ${response.status}`);
92
- }
93
- return (await response.json());
137
+ }, opts);
94
138
  }
95
139
  }
@@ -1,3 +1,4 @@
1
1
  export { SamyamaClient } from "./client.js";
2
2
  export { HttpTransport } from "./http-client.js";
3
+ export type { ConnectionOptions, RequestOptions } from "./http-client.js";
3
4
  export type { SdkNode, SdkEdge, QueryResult, ServerStatus, ErrorResponse, ClientOptions, GraphSchema, NodeType, EdgeType, IndexInfo, ConstraintInfo, CsvImportResult, JsonImportResult, } from "./types.js";
@@ -120,4 +120,10 @@ export interface JsonImportResult {
120
120
  export interface ClientOptions {
121
121
  /** Base URL for HTTP transport (default: http://localhost:8080) */
122
122
  url?: string;
123
+ /** Request deadline in milliseconds (default: 30000). */
124
+ timeoutMs?: number;
125
+ /** Retries for a timeout or connection failure (default: 2). */
126
+ maxRetries?: number;
127
+ /** Delay before the first retry, doubled each attempt (default: 100). */
128
+ retryBaseDelayMs?: number;
123
129
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "samyama-sdk",
3
- "version": "1.8.0",
3
+ "version": "1.10.0",
4
4
  "description": "TypeScript SDK for the Samyama Graph Database",
5
5
  "type": "module",
6
6
  "main": "dist/src/index.js",
@@ -8,7 +8,8 @@
8
8
  "types": "dist/src/index.d.ts",
9
9
  "files": [
10
10
  "dist/src/**/*.js",
11
- "dist/src/**/*.d.ts"
11
+ "dist/src/**/*.d.ts",
12
+ "README.md"
12
13
  ],
13
14
  "scripts": {
14
15
  "build": "tsc",