samyama-sdk 1.8.0 → 1.9.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/dist/src/client.d.ts +8 -0
- package/dist/src/client.js +15 -1
- package/dist/src/http-client.d.ts +65 -7
- package/dist/src/http-client.js +101 -57
- package/dist/src/index.d.ts +1 -0
- package/dist/src/types.d.ts +6 -0
- package/package.json +1 -1
package/dist/src/client.d.ts
CHANGED
|
@@ -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
|
}
|
package/dist/src/client.js
CHANGED
|
@@ -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
|
-
|
|
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
|
}
|
package/dist/src/http-client.js
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
27
|
-
|
|
28
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
}
|
package/dist/src/index.d.ts
CHANGED
|
@@ -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";
|
package/dist/src/types.d.ts
CHANGED
|
@@ -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
|
}
|