@sailresearch/sdk 0.2.14

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.
Files changed (89) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +126 -0
  3. package/dist/app.d.ts +23 -0
  4. package/dist/app.d.ts.map +1 -0
  5. package/dist/app.js +40 -0
  6. package/dist/app.js.map +1 -0
  7. package/dist/client.d.ts +119 -0
  8. package/dist/client.d.ts.map +1 -0
  9. package/dist/client.js +291 -0
  10. package/dist/client.js.map +1 -0
  11. package/dist/config.d.ts +8 -0
  12. package/dist/config.d.ts.map +1 -0
  13. package/dist/config.js +15 -0
  14. package/dist/config.js.map +1 -0
  15. package/dist/default-client.d.ts +13 -0
  16. package/dist/default-client.d.ts.map +1 -0
  17. package/dist/default-client.js +22 -0
  18. package/dist/default-client.js.map +1 -0
  19. package/dist/errors.d.ts +88 -0
  20. package/dist/errors.d.ts.map +1 -0
  21. package/dist/errors.js +201 -0
  22. package/dist/errors.js.map +1 -0
  23. package/dist/exec-process.d.ts +56 -0
  24. package/dist/exec-process.d.ts.map +1 -0
  25. package/dist/exec-process.js +105 -0
  26. package/dist/exec-process.js.map +1 -0
  27. package/dist/exec-stream.d.ts +21 -0
  28. package/dist/exec-stream.d.ts.map +1 -0
  29. package/dist/exec-stream.js +47 -0
  30. package/dist/exec-stream.js.map +1 -0
  31. package/dist/file-stream.d.ts +41 -0
  32. package/dist/file-stream.d.ts.map +1 -0
  33. package/dist/file-stream.js +86 -0
  34. package/dist/file-stream.js.map +1 -0
  35. package/dist/image.d.ts +90 -0
  36. package/dist/image.d.ts.map +1 -0
  37. package/dist/image.js +193 -0
  38. package/dist/image.js.map +1 -0
  39. package/dist/index.d.ts +31 -0
  40. package/dist/index.d.ts.map +1 -0
  41. package/dist/index.js +55 -0
  42. package/dist/index.js.map +1 -0
  43. package/dist/native.d.ts +10 -0
  44. package/dist/native.d.ts.map +1 -0
  45. package/dist/native.js +24 -0
  46. package/dist/native.js.map +1 -0
  47. package/dist/sailbox.d.ts +210 -0
  48. package/dist/sailbox.d.ts.map +1 -0
  49. package/dist/sailbox.js +339 -0
  50. package/dist/sailbox.js.map +1 -0
  51. package/dist/ssh.d.ts +16 -0
  52. package/dist/ssh.d.ts.map +1 -0
  53. package/dist/ssh.js +3 -0
  54. package/dist/ssh.js.map +1 -0
  55. package/dist/types/config.d.ts +21 -0
  56. package/dist/types/config.d.ts.map +1 -0
  57. package/dist/types/config.js +4 -0
  58. package/dist/types/config.js.map +1 -0
  59. package/dist/types/exec.d.ts +41 -0
  60. package/dist/types/exec.d.ts.map +1 -0
  61. package/dist/types/exec.js +4 -0
  62. package/dist/types/exec.js.map +1 -0
  63. package/dist/types/image.d.ts +50 -0
  64. package/dist/types/image.d.ts.map +1 -0
  65. package/dist/types/image.js +12 -0
  66. package/dist/types/image.js.map +1 -0
  67. package/dist/types/listener.d.ts +38 -0
  68. package/dist/types/listener.d.ts.map +1 -0
  69. package/dist/types/listener.js +21 -0
  70. package/dist/types/listener.js.map +1 -0
  71. package/dist/types/sailbox.d.ts +62 -0
  72. package/dist/types/sailbox.d.ts.map +1 -0
  73. package/dist/types/sailbox.js +19 -0
  74. package/dist/types/sailbox.js.map +1 -0
  75. package/dist/util.d.ts +3 -0
  76. package/dist/util.d.ts.map +1 -0
  77. package/dist/util.js +10 -0
  78. package/dist/util.js.map +1 -0
  79. package/dist/validate.d.ts +35 -0
  80. package/dist/validate.d.ts.map +1 -0
  81. package/dist/validate.js +87 -0
  82. package/dist/validate.js.map +1 -0
  83. package/dist/volume.d.ts +42 -0
  84. package/dist/volume.d.ts.map +1 -0
  85. package/dist/volume.js +72 -0
  86. package/dist/volume.js.map +1 -0
  87. package/native/index.d.ts +733 -0
  88. package/native/index.js +601 -0
  89. package/package.json +77 -0
package/dist/errors.js ADDED
@@ -0,0 +1,201 @@
1
+ "use strict";
2
+ /**
3
+ * Error taxonomy. The native addon throws errors whose `message` is a JSON
4
+ * envelope `{ sailErrorCode, message }` produced by the Rust core's canonical
5
+ * `SailError`; {@link rethrow} maps that code to one of the classes below so
6
+ * consumers can `catch (e) { if (e instanceof SailError) ... }` or match a
7
+ * specific subclass. Every error the core and bridge raise carries this
8
+ * envelope and maps to a `SailError` subclass; a truly unexpected native error
9
+ * (outside the taxonomy) surfaces unchanged.
10
+ */
11
+ Object.defineProperty(exports, "__esModule", { value: true });
12
+ exports.SailboxWorkerLostError = exports.SailboxExecRequestNotFoundError = exports.SailboxTerminatedError = exports.SailboxExecutionError = exports.ImageBuildError = exports.SailboxCreationError = exports.ApiError = exports.TransportError = exports.TimeoutError = exports.BrokenPipeError = exports.FileNotFoundError = exports.PermissionDeniedError = exports.NotFoundError = exports.InternalError = exports.InvalidArgumentError = exports.SailError = void 0;
13
+ exports.rethrow = rethrow;
14
+ exports.guard = guard;
15
+ exports.guardSync = guardSync;
16
+ /** Base class for every error surfaced by the SDK. */
17
+ class SailError extends Error {
18
+ /** Stable, language-neutral error code from the core (e.g. `"NotFound"`). */
19
+ code;
20
+ constructor(message, code = "SailError") {
21
+ super(message);
22
+ this.name = this.constructor.name;
23
+ this.code = code;
24
+ }
25
+ }
26
+ exports.SailError = SailError;
27
+ /** Invalid arguments or configuration (bad request, missing/invalid API key). */
28
+ class InvalidArgumentError extends SailError {
29
+ constructor(message) {
30
+ super(message, "InvalidArgument");
31
+ }
32
+ }
33
+ exports.InvalidArgumentError = InvalidArgumentError;
34
+ /** An unexpected internal SDK/core failure. */
35
+ class InternalError extends SailError {
36
+ constructor(message) {
37
+ super(message, "Internal");
38
+ }
39
+ }
40
+ exports.InternalError = InternalError;
41
+ /** The sailbox, volume, or other resource does not exist (or is another org's). */
42
+ class NotFoundError extends SailError {
43
+ constructor(message) {
44
+ super(message, "NotFound");
45
+ }
46
+ }
47
+ exports.NotFoundError = NotFoundError;
48
+ /** The credential is not permitted to perform the operation. */
49
+ class PermissionDeniedError extends SailError {
50
+ constructor(message) {
51
+ super(message, "PermissionDenied");
52
+ }
53
+ }
54
+ exports.PermissionDeniedError = PermissionDeniedError;
55
+ /** A remote file path does not exist. */
56
+ class FileNotFoundError extends SailError {
57
+ constructor(message) {
58
+ super(message, "FileNotFound");
59
+ }
60
+ }
61
+ exports.FileNotFoundError = FileNotFoundError;
62
+ /** A stream (e.g. exec stdin) was closed and can no longer be written. */
63
+ class BrokenPipeError extends SailError {
64
+ constructor(message) {
65
+ super(message, "BrokenPipe");
66
+ }
67
+ }
68
+ exports.BrokenPipeError = BrokenPipeError;
69
+ /** A request exceeded its timeout. */
70
+ class TimeoutError extends SailError {
71
+ constructor(message) {
72
+ super(message, "Timeout");
73
+ }
74
+ }
75
+ exports.TimeoutError = TimeoutError;
76
+ /** A network/connection transport failure. */
77
+ class TransportError extends SailError {
78
+ constructor(message) {
79
+ super(message, "Transport");
80
+ }
81
+ }
82
+ exports.TransportError = TransportError;
83
+ /** A transient, retryable server-side API failure. */
84
+ class ApiError extends SailError {
85
+ constructor(message) {
86
+ super(message, "Api");
87
+ }
88
+ }
89
+ exports.ApiError = ApiError;
90
+ /** A sailbox could not be created (provisioning failed). */
91
+ class SailboxCreationError extends SailError {
92
+ constructor(message) {
93
+ super(message, "SailboxCreationError");
94
+ }
95
+ }
96
+ exports.SailboxCreationError = SailboxCreationError;
97
+ /** A custom image could not be built or its local content could not be uploaded. */
98
+ class ImageBuildError extends SailError {
99
+ constructor(message) {
100
+ super(message, "ImageBuildError");
101
+ }
102
+ }
103
+ exports.ImageBuildError = ImageBuildError;
104
+ /** Base class for failures during an exec. */
105
+ class SailboxExecutionError extends SailError {
106
+ constructor(message, code = "SailboxExecutionError") {
107
+ super(message, code);
108
+ }
109
+ }
110
+ exports.SailboxExecutionError = SailboxExecutionError;
111
+ /** The sailbox was terminated while an exec was in flight. */
112
+ class SailboxTerminatedError extends SailboxExecutionError {
113
+ constructor(message) {
114
+ super(message, "SailboxTerminatedError");
115
+ }
116
+ }
117
+ exports.SailboxTerminatedError = SailboxTerminatedError;
118
+ /** The exec request could not be found on the worker (e.g. after a move). */
119
+ class SailboxExecRequestNotFoundError extends SailboxExecutionError {
120
+ constructor(message) {
121
+ super(message, "SailboxExecRequestNotFoundError");
122
+ }
123
+ }
124
+ exports.SailboxExecRequestNotFoundError = SailboxExecRequestNotFoundError;
125
+ /** The hosting worker was lost while an exec was in flight. */
126
+ class SailboxWorkerLostError extends SailboxExecutionError {
127
+ constructor(message) {
128
+ super(message, "SailboxWorkerLostError");
129
+ }
130
+ }
131
+ exports.SailboxWorkerLostError = SailboxWorkerLostError;
132
+ /** Maps a core error code to the class that represents it. */
133
+ const REGISTRY = {
134
+ InvalidArgument: (m) => new InvalidArgumentError(m),
135
+ Internal: (m) => new InternalError(m),
136
+ NotFound: (m) => new NotFoundError(m),
137
+ PermissionDenied: (m) => new PermissionDeniedError(m),
138
+ FileNotFound: (m) => new FileNotFoundError(m),
139
+ BrokenPipe: (m) => new BrokenPipeError(m),
140
+ Timeout: (m) => new TimeoutError(m),
141
+ Transport: (m) => new TransportError(m),
142
+ Api: (m) => new ApiError(m),
143
+ ImageBuildError: (m) => new ImageBuildError(m),
144
+ SailboxCreationError: (m) => new SailboxCreationError(m),
145
+ SailboxExecutionError: (m) => new SailboxExecutionError(m),
146
+ SailboxTerminatedError: (m) => new SailboxTerminatedError(m),
147
+ SailboxExecRequestNotFoundError: (m) => new SailboxExecRequestNotFoundError(m),
148
+ SailboxWorkerLostError: (m) => new SailboxWorkerLostError(m),
149
+ };
150
+ function tryMapNativeError(message) {
151
+ let parsed;
152
+ try {
153
+ parsed = JSON.parse(message);
154
+ }
155
+ catch {
156
+ return undefined;
157
+ }
158
+ if (!parsed || typeof parsed !== "object")
159
+ return undefined;
160
+ const code = parsed.sailErrorCode;
161
+ const inner = parsed.message;
162
+ if (typeof code !== "string")
163
+ return undefined;
164
+ const text = typeof inner === "string" ? inner : message;
165
+ const make = REGISTRY[code];
166
+ return make ? make(text) : new SailError(text, code);
167
+ }
168
+ /**
169
+ * Rethrow an error raised at the native boundary as the matching typed
170
+ * {@link SailError}. If it is not a recognized core error, the original is
171
+ * rethrown unchanged. Every SDK method funnels its native calls through this.
172
+ */
173
+ function rethrow(err) {
174
+ if (err instanceof Error) {
175
+ const mapped = tryMapNativeError(err.message);
176
+ if (mapped)
177
+ throw mapped;
178
+ }
179
+ throw err;
180
+ }
181
+ /** Run an async native call, mapping any boundary error to a typed
182
+ * {@link SailError} via {@link rethrow}. The standard wrapper for a method whose
183
+ * body is a single native call. */
184
+ async function guard(fn) {
185
+ try {
186
+ return await fn();
187
+ }
188
+ catch (err) {
189
+ rethrow(err);
190
+ }
191
+ }
192
+ /** Synchronous {@link guard} for a native call that returns a value directly. */
193
+ function guardSync(fn) {
194
+ try {
195
+ return fn();
196
+ }
197
+ catch (err) {
198
+ rethrow(err);
199
+ }
200
+ }
201
+ //# sourceMappingURL=errors.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,56 @@
1
+ import type { ExecProcessHandle } from "./native.js";
2
+ import { ExecStream } from "./exec-stream.js";
3
+ import type { CancelOptions, ExecResult } from "./types/exec.js";
4
+ /**
5
+ * A live command running in a sailbox. Stream {@link stdout}/{@link stderr},
6
+ * write to {@link writeStdin}, and {@link wait} for the result. Not killed on GC;
7
+ * call {@link close} to detach, or {@link cancel} to stop the command.
8
+ *
9
+ * @example
10
+ * ```ts
11
+ * const proc = await box.exec(["bash", "-lc", "echo hi"]);
12
+ * for await (const line of proc.stdout) process.stdout.write(line);
13
+ * const result = await proc.wait();
14
+ * console.log(result.exitCode);
15
+ * ```
16
+ */
17
+ export declare class ExecProcess {
18
+ private readonly handle;
19
+ /** Stdout as an async iterable of decoded chunks. */
20
+ readonly stdout: ExecStream;
21
+ /** Alias for {@link stdout}: under a pty the two output streams merge onto
22
+ * stdout, and `output` names that merged terminal stream. */
23
+ get output(): ExecStream;
24
+ /** Stderr as an async iterable of decoded chunks. */
25
+ readonly stderr: ExecStream;
26
+ constructor(handle: ExecProcessHandle);
27
+ /** The durable exec request id. */
28
+ get execRequestId(): string;
29
+ /** The idempotency key used to launch the command. */
30
+ get idempotencyKey(): string;
31
+ /** Await the authoritative result (exit code, buffered output, flags). */
32
+ wait(): Promise<ExecResult>;
33
+ /** Wait up to `timeoutSeconds` for the streams to end; returns whether they
34
+ * did. `Infinity` waits indefinitely. */
35
+ waitStreamEnded(timeoutSeconds: number): Promise<boolean>;
36
+ /** Write to the command's stdin (requires `openStdin`). */
37
+ writeStdin(data: Buffer | Uint8Array | string): Promise<void>;
38
+ /** Close the command's stdin (send EOF). */
39
+ closeStdin(): Promise<void>;
40
+ /** Cancel the command (SIGINT by default, SIGKILL with `force`). */
41
+ cancel(options?: CancelOptions): Promise<void>;
42
+ /** Resize the pty (no-op without one). */
43
+ resize(cols: number, rows: number): Promise<void>;
44
+ /** The exit code if the exit frame has arrived on the stream, else `null`.
45
+ * Throws for a worker-lost exec (no real exit code), as {@link wait} does. */
46
+ poll(): number | null;
47
+ /** Stop the output pump and detach (does not kill the command). Call this on
48
+ * early exit from streaming a long-running command so the stream is not held
49
+ * until GC. */
50
+ close(): void;
51
+ /** `using` support: detaches on scope exit. */
52
+ [Symbol.dispose](): void;
53
+ /** `await using` support: detaches on scope exit. */
54
+ [Symbol.asyncDispose](): Promise<void>;
55
+ }
56
+ //# sourceMappingURL=exec-process.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"exec-process.d.ts","sourceRoot":"","sources":["../src/exec-process.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAI9C,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEjE;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAW;IAWV,OAAO,CAAC,QAAQ,CAAC,MAAM;IAVnC,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B;iEAC6D;IAC7D,IAAI,MAAM,IAAI,UAAU,CAEvB;IACD,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;gBAEC,MAAM,EAAE,iBAAiB;IAKtD,mCAAmC;IACnC,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,sDAAsD;IACtD,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED,0EAA0E;IAC1E,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC;IAI3B;6CACyC;IACnC,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ/D,2DAA2D;IAC3D,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7D,4CAA4C;IAC5C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,oEAAoE;IAC9D,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAUxD,0CAA0C;IACpC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAavD;kFAC8E;IAC9E,IAAI,IAAI,MAAM,GAAG,IAAI;IAIrB;;mBAEe;IACf,KAAK,IAAI,IAAI;IAIb,+CAA+C;IAC/C,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;IAIxB,qDAAqD;IAC/C,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7C"}
@@ -0,0 +1,105 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.ExecProcess = void 0;
4
+ const exec_stream_js_1 = require("./exec-stream.js");
5
+ const errors_js_1 = require("./errors.js");
6
+ const validate_js_1 = require("./validate.js");
7
+ const util_js_1 = require("./util.js");
8
+ /**
9
+ * A live command running in a sailbox. Stream {@link stdout}/{@link stderr},
10
+ * write to {@link writeStdin}, and {@link wait} for the result. Not killed on GC;
11
+ * call {@link close} to detach, or {@link cancel} to stop the command.
12
+ *
13
+ * @example
14
+ * ```ts
15
+ * const proc = await box.exec(["bash", "-lc", "echo hi"]);
16
+ * for await (const line of proc.stdout) process.stdout.write(line);
17
+ * const result = await proc.wait();
18
+ * console.log(result.exitCode);
19
+ * ```
20
+ */
21
+ class ExecProcess {
22
+ handle;
23
+ /** Stdout as an async iterable of decoded chunks. */
24
+ stdout;
25
+ /** Alias for {@link stdout}: under a pty the two output streams merge onto
26
+ * stdout, and `output` names that merged terminal stream. */
27
+ get output() {
28
+ return this.stdout;
29
+ }
30
+ /** Stderr as an async iterable of decoded chunks. */
31
+ stderr;
32
+ constructor(handle) {
33
+ this.handle = handle;
34
+ this.stdout = new exec_stream_js_1.ExecStream(handle.stdoutReader());
35
+ this.stderr = new exec_stream_js_1.ExecStream(handle.stderrReader());
36
+ }
37
+ /** The durable exec request id. */
38
+ get execRequestId() {
39
+ return this.handle.execRequestId;
40
+ }
41
+ /** The idempotency key used to launch the command. */
42
+ get idempotencyKey() {
43
+ return this.handle.idempotencyKey;
44
+ }
45
+ /** Await the authoritative result (exit code, buffered output, flags). */
46
+ wait() {
47
+ return (0, errors_js_1.guard)(() => this.handle.wait());
48
+ }
49
+ /** Wait up to `timeoutSeconds` for the streams to end; returns whether they
50
+ * did. `Infinity` waits indefinitely. */
51
+ async waitStreamEnded(timeoutSeconds) {
52
+ // NaN would cross the boundary as a zero wait and misread the streams.
53
+ if (Number.isNaN(timeoutSeconds)) {
54
+ throw new errors_js_1.InvalidArgumentError("timeoutSeconds must not be NaN");
55
+ }
56
+ return (0, errors_js_1.guard)(() => this.handle.waitStreamEnded(timeoutSeconds));
57
+ }
58
+ /** Write to the command's stdin (requires `openStdin`). */
59
+ writeStdin(data) {
60
+ return (0, errors_js_1.guard)(() => this.handle.writeStdin((0, util_js_1.toBuffer)(data)));
61
+ }
62
+ /** Close the command's stdin (send EOF). */
63
+ closeStdin() {
64
+ return (0, errors_js_1.guard)(() => this.handle.closeStdin());
65
+ }
66
+ /** Cancel the command (SIGINT by default, SIGKILL with `force`). */
67
+ async cancel(options = {}) {
68
+ (0, validate_js_1.validateRetryBudget)(options.retryTimeoutSeconds);
69
+ return (0, errors_js_1.guard)(() => this.handle.cancel(options.force ?? false, options.retryTimeoutSeconds ?? 0));
70
+ }
71
+ /** Resize the pty (no-op without one). */
72
+ async resize(cols, rows) {
73
+ // Fractional dimensions would truncate at the native u32 boundary.
74
+ for (const [name, value] of [
75
+ ["cols", cols],
76
+ ["rows", rows],
77
+ ]) {
78
+ if (!Number.isInteger(value) || value < 1) {
79
+ throw new errors_js_1.InvalidArgumentError(`${name} must be a positive integer`);
80
+ }
81
+ }
82
+ return (0, errors_js_1.guard)(() => this.handle.resize(cols, rows));
83
+ }
84
+ /** The exit code if the exit frame has arrived on the stream, else `null`.
85
+ * Throws for a worker-lost exec (no real exit code), as {@link wait} does. */
86
+ poll() {
87
+ return (0, errors_js_1.guardSync)(() => this.handle.poll());
88
+ }
89
+ /** Stop the output pump and detach (does not kill the command). Call this on
90
+ * early exit from streaming a long-running command so the stream is not held
91
+ * until GC. */
92
+ close() {
93
+ (0, errors_js_1.guardSync)(() => this.handle.close());
94
+ }
95
+ /** `using` support: detaches on scope exit. */
96
+ [Symbol.dispose]() {
97
+ this.close();
98
+ }
99
+ /** `await using` support: detaches on scope exit. */
100
+ async [Symbol.asyncDispose]() {
101
+ this.close();
102
+ }
103
+ }
104
+ exports.ExecProcess = ExecProcess;
105
+ //# sourceMappingURL=exec-process.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"exec-process.js","sourceRoot":"","sources":["../src/exec-process.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,21 @@
1
+ import { Readable } from "node:stream";
2
+ import type { AsyncStreamReaderHandle } from "./native.js";
3
+ /**
4
+ * An async-iterable view of one exec stream (stdout or stderr). Chunks are
5
+ * decoded UTF-8 strings; iteration ends at end of stream.
6
+ *
7
+ * @example
8
+ * ```ts
9
+ * for await (const chunk of proc.stdout) process.stdout.write(chunk);
10
+ * ```
11
+ */
12
+ export declare class ExecStream implements AsyncIterable<string> {
13
+ private readonly reader;
14
+ constructor(reader: AsyncStreamReaderHandle);
15
+ [Symbol.asyncIterator](): AsyncIterator<string>;
16
+ /** Adapt to a Node `Readable` (e.g. to `.pipe()` it somewhere). */
17
+ toReadable(): Readable;
18
+ /** Collect the whole stream into a single string. */
19
+ text(): Promise<string>;
20
+ }
21
+ //# sourceMappingURL=exec-stream.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"exec-stream.d.ts","sourceRoot":"","sources":["../src/exec-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAG3D;;;;;;;;GAQG;AACH,qBAAa,UAAW,YAAW,aAAa,CAAC,MAAM,CAAC;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,uBAAuB;IAErD,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC;IAatD,mEAAmE;IACnE,UAAU,IAAI,QAAQ;IAItB,qDAAqD;IAC/C,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAK9B"}
@@ -0,0 +1,47 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.ExecStream = void 0;
4
+ const node_stream_1 = require("node:stream");
5
+ const errors_js_1 = require("./errors.js");
6
+ /**
7
+ * An async-iterable view of one exec stream (stdout or stderr). Chunks are
8
+ * decoded UTF-8 strings; iteration ends at end of stream.
9
+ *
10
+ * @example
11
+ * ```ts
12
+ * for await (const chunk of proc.stdout) process.stdout.write(chunk);
13
+ * ```
14
+ */
15
+ class ExecStream {
16
+ reader;
17
+ constructor(reader) {
18
+ this.reader = reader;
19
+ }
20
+ async *[Symbol.asyncIterator]() {
21
+ for (;;) {
22
+ let chunk;
23
+ try {
24
+ chunk = await this.reader.next();
25
+ }
26
+ catch (err) {
27
+ (0, errors_js_1.rethrow)(err);
28
+ }
29
+ if (chunk === null)
30
+ return;
31
+ yield chunk;
32
+ }
33
+ }
34
+ /** Adapt to a Node `Readable` (e.g. to `.pipe()` it somewhere). */
35
+ toReadable() {
36
+ return node_stream_1.Readable.from(this);
37
+ }
38
+ /** Collect the whole stream into a single string. */
39
+ async text() {
40
+ let out = "";
41
+ for await (const chunk of this)
42
+ out += chunk;
43
+ return out;
44
+ }
45
+ }
46
+ exports.ExecStream = ExecStream;
47
+ //# sourceMappingURL=exec-stream.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"exec-stream.js","sourceRoot":"","sources":["../src/exec-stream.ts"],"names":[],"mappings":";;;AAAA,6CAAuC;AAEvC,2CAAsC;AAEtC;;;;;;;;GAQG;AACH,MAAa,UAAU;IACQ;IAA7B,YAA6B,MAA+B;QAA/B,WAAM,GAAN,MAAM,CAAyB;IAAG,CAAC;IAEhE,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;QAC3B,SAAS,CAAC;YACR,IAAI,KAAoB,CAAC;YACzB,IAAI,CAAC;gBACH,KAAK,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACnC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAA,mBAAO,EAAC,GAAG,CAAC,CAAC;YACf,CAAC;YACD,IAAI,KAAK,KAAK,IAAI;gBAAE,OAAO;YAC3B,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,mEAAmE;IACnE,UAAU;QACR,OAAO,sBAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,qDAAqD;IACrD,KAAK,CAAC,IAAI;QACR,IAAI,GAAG,GAAG,EAAE,CAAC;QACb,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,IAAI;YAAE,GAAG,IAAI,KAAK,CAAC;QAC7C,OAAO,GAAG,CAAC;IACb,CAAC;CACF;AA3BD,gCA2BC"}
@@ -0,0 +1,41 @@
1
+ import { Readable } from "node:stream";
2
+ import type { FileReaderHandle, FileWriterHandle } from "./native.js";
3
+ /**
4
+ * An async-iterable download of a guest file. Chunks are `Buffer`s; iteration
5
+ * ends at end of file. The underlying stream is released when iteration finishes
6
+ * or is abandoned (via a generator `finally`), or explicitly via {@link close}.
7
+ */
8
+ export declare class FileStream implements AsyncIterable<Buffer> {
9
+ private readonly reader;
10
+ constructor(reader: FileReaderHandle);
11
+ [Symbol.asyncIterator](): AsyncIterator<Buffer>;
12
+ /** Release the underlying download stream (idempotent). */
13
+ close(): Promise<void>;
14
+ /** `await using` support. */
15
+ [Symbol.asyncDispose](): Promise<void>;
16
+ /** Adapt to a Node `Readable`. */
17
+ toReadable(): Readable;
18
+ /** Collect the whole file into a single `Buffer`. */
19
+ bytes(): Promise<Buffer>;
20
+ }
21
+ /**
22
+ * A streaming write to a guest file. Push chunks with {@link write}, then
23
+ * confirm with {@link finish} — only `finish` commits the write. A writer
24
+ * that goes away without finishing ({@link abort}, an error path, or garbage
25
+ * collection) cancels the transfer instead; the guest file state is then
26
+ * unspecified.
27
+ */
28
+ export declare class FileWriter {
29
+ private readonly handle;
30
+ constructor(handle: FileWriterHandle);
31
+ /** Write bytes (a `string` is encoded as UTF-8). The core splits them into
32
+ * transport-sized chunks. */
33
+ write(data: Buffer | Uint8Array | string): Promise<void>;
34
+ /** Abort the write: cancel the RPC so the server does not commit it.
35
+ * Idempotent. A later {@link finish} reports the abort instead of
36
+ * succeeding; the guest file state after an abort is unspecified. */
37
+ abort(): void;
38
+ /** Confirm the write, creating an empty file if nothing was written. */
39
+ finish(): Promise<void>;
40
+ }
41
+ //# sourceMappingURL=file-stream.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"file-stream.d.ts","sourceRoot":"","sources":["../src/file-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAItE;;;;GAIG;AACH,qBAAa,UAAW,YAAW,aAAa,CAAC,MAAM,CAAC;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,gBAAgB;IAE9C,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC;IAiBtD,2DAA2D;IAC3D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,6BAA6B;IACvB,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5C,kCAAkC;IAClC,UAAU,IAAI,QAAQ;IAItB,qDAAqD;IAC/C,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;CAK/B;AAED;;;;;;GAMG;AACH,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,gBAAgB;IAErD;iCAC6B;IAC7B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxD;;yEAEqE;IACrE,KAAK,IAAI,IAAI;IAIb,wEAAwE;IACxE,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAGxB"}
@@ -0,0 +1,86 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.FileWriter = exports.FileStream = void 0;
4
+ const node_stream_1 = require("node:stream");
5
+ const errors_js_1 = require("./errors.js");
6
+ const util_js_1 = require("./util.js");
7
+ /**
8
+ * An async-iterable download of a guest file. Chunks are `Buffer`s; iteration
9
+ * ends at end of file. The underlying stream is released when iteration finishes
10
+ * or is abandoned (via a generator `finally`), or explicitly via {@link close}.
11
+ */
12
+ class FileStream {
13
+ reader;
14
+ constructor(reader) {
15
+ this.reader = reader;
16
+ }
17
+ async *[Symbol.asyncIterator]() {
18
+ try {
19
+ for (;;) {
20
+ let chunk;
21
+ try {
22
+ chunk = await this.reader.next();
23
+ }
24
+ catch (err) {
25
+ (0, errors_js_1.rethrow)(err);
26
+ }
27
+ if (chunk === null)
28
+ return;
29
+ yield chunk;
30
+ }
31
+ }
32
+ finally {
33
+ await this.close();
34
+ }
35
+ }
36
+ /** Release the underlying download stream (idempotent). */
37
+ close() {
38
+ return (0, errors_js_1.guard)(() => this.reader.close());
39
+ }
40
+ /** `await using` support. */
41
+ async [Symbol.asyncDispose]() {
42
+ await this.close();
43
+ }
44
+ /** Adapt to a Node `Readable`. */
45
+ toReadable() {
46
+ return node_stream_1.Readable.from(this);
47
+ }
48
+ /** Collect the whole file into a single `Buffer`. */
49
+ async bytes() {
50
+ const chunks = [];
51
+ for await (const chunk of this)
52
+ chunks.push(chunk);
53
+ return Buffer.concat(chunks);
54
+ }
55
+ }
56
+ exports.FileStream = FileStream;
57
+ /**
58
+ * A streaming write to a guest file. Push chunks with {@link write}, then
59
+ * confirm with {@link finish} — only `finish` commits the write. A writer
60
+ * that goes away without finishing ({@link abort}, an error path, or garbage
61
+ * collection) cancels the transfer instead; the guest file state is then
62
+ * unspecified.
63
+ */
64
+ class FileWriter {
65
+ handle;
66
+ constructor(handle) {
67
+ this.handle = handle;
68
+ }
69
+ /** Write bytes (a `string` is encoded as UTF-8). The core splits them into
70
+ * transport-sized chunks. */
71
+ write(data) {
72
+ return (0, errors_js_1.guard)(() => this.handle.write((0, util_js_1.toBuffer)(data)));
73
+ }
74
+ /** Abort the write: cancel the RPC so the server does not commit it.
75
+ * Idempotent. A later {@link finish} reports the abort instead of
76
+ * succeeding; the guest file state after an abort is unspecified. */
77
+ abort() {
78
+ (0, errors_js_1.guardSync)(() => this.handle.abort());
79
+ }
80
+ /** Confirm the write, creating an empty file if nothing was written. */
81
+ finish() {
82
+ return (0, errors_js_1.guard)(() => this.handle.finish());
83
+ }
84
+ }
85
+ exports.FileWriter = FileWriter;
86
+ //# sourceMappingURL=file-stream.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"file-stream.js","sourceRoot":"","sources":["../src/file-stream.ts"],"names":[],"mappings":";;;AAAA,6CAAuC;AAEvC,2CAAwD;AACxD,uCAAqC;AAErC;;;;GAIG;AACH,MAAa,UAAU;IACQ;IAA7B,YAA6B,MAAwB;QAAxB,WAAM,GAAN,MAAM,CAAkB;IAAG,CAAC;IAEzD,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;QAC3B,IAAI,CAAC;YACH,SAAS,CAAC;gBACR,IAAI,KAAoB,CAAC;gBACzB,IAAI,CAAC;oBACH,KAAK,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;gBACnC,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,IAAA,mBAAO,EAAC,GAAG,CAAC,CAAC;gBACf,CAAC;gBACD,IAAI,KAAK,KAAK,IAAI;oBAAE,OAAO;gBAC3B,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC;IACH,CAAC;IAED,2DAA2D;IAC3D,KAAK;QACH,OAAO,IAAA,iBAAK,EAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED,6BAA6B;IAC7B,KAAK,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;QACzB,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED,kCAAkC;IAClC,UAAU;QACR,OAAO,sBAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,qDAAqD;IACrD,KAAK,CAAC,KAAK;QACT,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,IAAI;YAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;CACF;AAzCD,gCAyCC;AAED;;;;;;GAMG;AACH,MAAa,UAAU;IACQ;IAA7B,YAA6B,MAAwB;QAAxB,WAAM,GAAN,MAAM,CAAkB;IAAG,CAAC;IAEzD;iCAC6B;IAC7B,KAAK,CAAC,IAAkC;QACtC,OAAO,IAAA,iBAAK,EAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAA,kBAAQ,EAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACxD,CAAC;IAED;;yEAEqE;IACrE,KAAK;QACH,IAAA,qBAAS,EAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IACvC,CAAC;IAED,wEAAwE;IACxE,MAAM;QACJ,OAAO,IAAA,iBAAK,EAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC3C,CAAC;CACF;AApBD,gCAoBC"}