@tinyshed/tinystore 0.1.0 → 0.1.1

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 (69) hide show
  1. package/dist/blobs.d.ts +1 -1
  2. package/dist/blobs.js +13 -5
  3. package/dist/cancel.d.ts +16 -2
  4. package/dist/cancel.js +36 -2
  5. package/dist/channels.js +20 -6
  6. package/dist/config.d.ts +49 -1
  7. package/dist/config.js +86 -7
  8. package/dist/connection.d.ts +52 -10
  9. package/dist/connection.js +305 -73
  10. package/dist/handles.d.ts +10 -1
  11. package/dist/handles.js +27 -4
  12. package/dist/index.d.ts +4 -4
  13. package/dist/jobs.d.ts +33 -1
  14. package/dist/jobs.js +45 -0
  15. package/dist/logger.d.ts +22 -10
  16. package/dist/logger.js +118 -28
  17. package/dist/metrics.d.ts +19 -0
  18. package/dist/metrics.js +22 -1
  19. package/dist/query.js +33 -9
  20. package/dist/records.d.ts +30 -2
  21. package/dist/records.js +8 -0
  22. package/dist/runtime/addon.js +3 -2
  23. package/dist/runtime/bun.js +33 -12
  24. package/dist/runtime/node.js +30 -8
  25. package/dist/runtime/pipe.d.ts +2 -0
  26. package/dist/runtime/pipe.js +45 -20
  27. package/dist/runtime/shared.d.ts +28 -4
  28. package/dist/runtime/shared.js +125 -13
  29. package/dist/runtime.d.ts +28 -6
  30. package/dist/session.d.ts +9 -5
  31. package/dist/session.js +113 -31
  32. package/dist/sql.d.ts +18 -5
  33. package/dist/sql.js +44 -11
  34. package/dist/store.d.ts +25 -11
  35. package/dist/store.js +67 -9
  36. package/dist/wire/codec.d.ts +5 -0
  37. package/dist/wire/codec.js +10 -0
  38. package/dist/wire/frame.d.ts +2 -0
  39. package/dist/wire/frame.js +4 -0
  40. package/dist/wire/msgpack.d.ts +7 -3
  41. package/dist/wire/msgpack.js +11 -4
  42. package/dist/wire/protocol.d.ts +246 -36
  43. package/dist/wire/protocol.js +387 -101
  44. package/package.json +9 -8
  45. package/src/blobs.ts +13 -5
  46. package/src/cancel.ts +44 -2
  47. package/src/channels.ts +21 -6
  48. package/src/config.ts +138 -12
  49. package/src/connection.ts +377 -77
  50. package/src/handles.ts +32 -4
  51. package/src/index.ts +5 -0
  52. package/src/jobs.ts +63 -0
  53. package/src/logger.ts +158 -40
  54. package/src/metrics.ts +46 -1
  55. package/src/query.ts +33 -13
  56. package/src/records.ts +40 -2
  57. package/src/runtime/addon.ts +3 -2
  58. package/src/runtime/bun.ts +44 -9
  59. package/src/runtime/node.ts +30 -5
  60. package/src/runtime/pipe.ts +49 -19
  61. package/src/runtime/shared.ts +137 -16
  62. package/src/runtime.ts +31 -6
  63. package/src/session.ts +129 -30
  64. package/src/sql.ts +48 -14
  65. package/src/store.ts +81 -14
  66. package/src/wire/codec.ts +11 -0
  67. package/src/wire/frame.ts +5 -0
  68. package/src/wire/msgpack.ts +11 -4
  69. package/src/wire/protocol.ts +404 -103
package/dist/blobs.d.ts CHANGED
@@ -147,7 +147,7 @@ export declare class FileBytes {
147
147
  #private;
148
148
  readonly size: number;
149
149
  /** File bytes come from `files.get` and `slice`. */
150
- constructor(size: number, stream: () => ReadableStream<Uint8Array>);
150
+ constructor(size: number, stream: () => ReadableStream<Uint8Array>, held?: Uint8Array);
151
151
  /** Its bytes as they come, the credit of each given back once it is taken. */
152
152
  stream(): ReadableStream<Uint8Array>;
153
153
  bytes(): Promise<Uint8Array<ArrayBuffer>>;
package/dist/blobs.js CHANGED
@@ -66,7 +66,8 @@ export class Files {
66
66
  */
67
67
  async get(path) {
68
68
  const answer = await this.#call('blobs.get', handle => BlobsAt.encode({ handle, folder: this.#folder, path }), 'read');
69
- const got = BlobsGot.decode(answer);
69
+ // the answer is this call's alone: the file's bytes stay where they came
70
+ const got = BlobsGot.view(answer);
70
71
  if (got.info === undefined) {
71
72
  return undefined;
72
73
  }
@@ -346,16 +347,23 @@ export class Upload {
346
347
  export class FileBytes {
347
348
  size;
348
349
  #stream;
350
+ /** its bytes when they came with the get, which each read copies once */
351
+ #held;
349
352
  /** File bytes come from `files.get` and `slice`. */
350
- constructor(size, stream) {
353
+ constructor(size, stream, held) {
351
354
  this.size = size;
352
355
  this.#stream = stream;
356
+ this.#held = held;
353
357
  }
354
358
  /** Its bytes as they come, the credit of each given back once it is taken. */
355
359
  stream() {
356
360
  return this.#stream();
357
361
  }
358
362
  async bytes() {
363
+ if (this.#held !== undefined) {
364
+ // a copy, which a Buffer's slice under Node is not
365
+ return new Uint8Array(this.#held);
366
+ }
359
367
  const whole = new Uint8Array(this.size);
360
368
  let at = 0;
361
369
  for await (const piece of this.stream()) {
@@ -391,7 +399,7 @@ export class StoredFile extends FileBytes {
391
399
  #read;
392
400
  /** Stored files come from `files.get`. */
393
401
  constructor(info, whole, read) {
394
- super(info.size, () => (whole === undefined ? read() : streamOf(whole)));
402
+ super(info.size, () => (whole === undefined ? read() : streamOf(whole)), whole);
395
403
  this.path = info.path;
396
404
  this.etag = info.etag;
397
405
  this.contentType = info.contentType;
@@ -412,7 +420,7 @@ export class StoredFile extends FileBytes {
412
420
  const whole = this.#whole;
413
421
  if (whole !== undefined) {
414
422
  const bytes = whole.subarray(from, to);
415
- return new FileBytes(bytes.length, () => streamOf(bytes));
423
+ return new FileBytes(bytes.length, () => streamOf(bytes), bytes);
416
424
  }
417
425
  return new FileBytes(to - from, () => this.#read(from, to - from));
418
426
  }
@@ -430,7 +438,7 @@ function streamOf(bytes) {
430
438
  return new ReadableStream({
431
439
  start(controller) {
432
440
  if (bytes.length > 0) {
433
- controller.enqueue(bytes.slice());
441
+ controller.enqueue(new Uint8Array(bytes));
434
442
  }
435
443
  controller.close();
436
444
  },
package/dist/cancel.d.ts CHANGED
@@ -1,7 +1,8 @@
1
1
  /**
2
2
  * Runs fn under a signal: every call it makes, a kv get, a statement, a
3
- * scan, rejects once the signal aborts, its stream cancelled on the wire. A
4
- * call given a signal of its own, as work and put take one, keeps that one.
3
+ * scan, open and connect too, rejects once the signal aborts, its stream
4
+ * cancelled on the wire, with CancelledError. A call given a signal of its
5
+ * own, as work and put take one, keeps that one.
5
6
  *
6
7
  * ```ts
7
8
  * await withSignal(AbortSignal.timeout(2000), async () => {
@@ -12,3 +13,16 @@
12
13
  export declare function withSignal<T>(signal: AbortSignal, fn: () => T): T;
13
14
  /** The signal the caller runs under, from withSignal. */
14
15
  export declare function currentSignal(): AbortSignal | undefined;
16
+ /**
17
+ * Runs fn under no caller's signal: a dial that every caller of a store
18
+ * shares stops for none of theirs, only for the store's close.
19
+ */
20
+ export declare function withoutSignal<T>(fn: () => T): T;
21
+ /** Throws the CancelledError of a call whose signal has aborted, rather than the signal's own reason. */
22
+ export declare function checkSignal(signal: AbortSignal | undefined): void;
23
+ /**
24
+ * What a promise gives, unless the signal aborts first: the caller then
25
+ * stops waiting with the error `cancelled` makes, and the promise goes on
26
+ * for whoever else waits on it.
27
+ */
28
+ export declare function unlessCancelled<T>(promise: Promise<T>, signal: AbortSignal | undefined, cancelled?: () => Error): Promise<T>;
package/dist/cancel.js CHANGED
@@ -1,11 +1,13 @@
1
1
  // The signal a call runs under, as a Go call carries its context: every call
2
2
  // made inside withSignal, and inside what it awaits, ends when it aborts.
3
3
  import { AsyncLocalStorage } from 'node:async_hooks';
4
+ import { CancelledError } from './errors.js';
4
5
  const carried = new AsyncLocalStorage();
5
6
  /**
6
7
  * Runs fn under a signal: every call it makes, a kv get, a statement, a
7
- * scan, rejects once the signal aborts, its stream cancelled on the wire. A
8
- * call given a signal of its own, as work and put take one, keeps that one.
8
+ * scan, open and connect too, rejects once the signal aborts, its stream
9
+ * cancelled on the wire, with CancelledError. A call given a signal of its
10
+ * own, as work and put take one, keeps that one.
9
11
  *
10
12
  * ```ts
11
13
  * await withSignal(AbortSignal.timeout(2000), async () => {
@@ -20,3 +22,35 @@ export function withSignal(signal, fn) {
20
22
  export function currentSignal() {
21
23
  return carried.getStore();
22
24
  }
25
+ /**
26
+ * Runs fn under no caller's signal: a dial that every caller of a store
27
+ * shares stops for none of theirs, only for the store's close.
28
+ */
29
+ export function withoutSignal(fn) {
30
+ return carried.exit(fn);
31
+ }
32
+ /** Throws the CancelledError of a call whose signal has aborted, rather than the signal's own reason. */
33
+ export function checkSignal(signal) {
34
+ if (signal?.aborted) {
35
+ throw new CancelledError('the call was cancelled');
36
+ }
37
+ }
38
+ /**
39
+ * What a promise gives, unless the signal aborts first: the caller then
40
+ * stops waiting with the error `cancelled` makes, and the promise goes on
41
+ * for whoever else waits on it.
42
+ */
43
+ export function unlessCancelled(promise, signal, cancelled = () => new CancelledError('the call was cancelled')) {
44
+ if (signal === undefined) {
45
+ return promise;
46
+ }
47
+ if (signal.aborted) {
48
+ promise.catch(() => { });
49
+ return Promise.reject(cancelled());
50
+ }
51
+ return new Promise((resolve, reject) => {
52
+ const abort = () => reject(cancelled());
53
+ signal.addEventListener('abort', abort, { once: true });
54
+ promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
55
+ });
56
+ }
package/dist/channels.js CHANGED
@@ -72,10 +72,11 @@ export class Channel {
72
72
  }
73
73
  throw err;
74
74
  }
75
- if (!first) {
76
- await told.missed({ reason: 'reconnect' });
77
- }
75
+ const unfollow = this.#link.follow(stream);
78
76
  try {
77
+ if (!first) {
78
+ await told.missed({ reason: 'reconnect' });
79
+ }
79
80
  for (;;) {
80
81
  const event = await stream.next();
81
82
  if (event.end) {
@@ -98,6 +99,7 @@ export class Channel {
98
99
  }
99
100
  finally {
100
101
  stream.cancel();
102
+ unfollow();
101
103
  }
102
104
  }
103
105
  }
@@ -121,6 +123,7 @@ export class Subscription {
121
123
  #asked;
122
124
  #shown;
123
125
  #stream;
126
+ #unfollow = () => { };
124
127
  #stopped = false;
125
128
  #done = Promise.resolve();
126
129
  /** A subscription comes from `channel.subscribe`. */
@@ -143,9 +146,15 @@ export class Subscription {
143
146
  }
144
147
  /** Registers the subscription, then runs its handler in the background. */
145
148
  async start(handler, options) {
146
- this.#stream = await subscribed(this.#link, this.#asked);
149
+ this.#take(await subscribed(this.#link, this.#asked));
147
150
  const told = new Told(this.#shown, options?.onMissed, options?.onError);
148
- this.#done = this.#run(handler, told);
151
+ this.#done = this.#run(handler, told).finally(() => this.#unfollow());
152
+ }
153
+ /** Makes a stream the subscription's, which the store's close cancels. */
154
+ #take(stream) {
155
+ this.#unfollow();
156
+ this.#stream = stream;
157
+ this.#unfollow = this.#link.follow(stream);
149
158
  }
150
159
  async #run(handler, told) {
151
160
  for (;;) {
@@ -166,7 +175,12 @@ export class Subscription {
166
175
  if (!(made instanceof Stream)) {
167
176
  return told.ended(made, this.#stopped);
168
177
  }
169
- this.#stream = made;
178
+ this.#take(made);
179
+ // a stop while it subscribed again cancelled the stream before this one
180
+ if (this.#stopped) {
181
+ made.cancel();
182
+ return;
183
+ }
170
184
  await told.missed({ reason: 'reconnect' });
171
185
  }
172
186
  }
package/dist/config.d.ts CHANGED
@@ -1,6 +1,8 @@
1
1
  import type { Link } from './connection.ts';
2
2
  import { type StandardSchemaV1 } from './schema.ts';
3
3
  import { type DurationText } from './time.ts';
4
+ import type { Read } from './wire/codec.ts';
5
+ import { type ConfigOrigin } from './wire/protocol.ts';
4
6
  declare const mark = "~setting";
5
7
  declare const layerMark = "~layer";
6
8
  type Kind = 'text' | 'integer' | 'number' | 'boolean' | 'duration' | 'object' | 'any' | {
@@ -121,7 +123,47 @@ export interface ExplainLine {
121
123
  readonly from: string;
122
124
  /** the values it went over, newest first */
123
125
  readonly over: string;
126
+ /**
127
+ * Every value the setting was given, newest first: its own, then the ones
128
+ * it went over. `from` is `String(given[0].from)`. It is empty from a
129
+ * server before 0.1.1. `console.table` and a spread leave it out, and JSON
130
+ * keeps it.
131
+ */
132
+ readonly given: readonly ExplainGiven[];
133
+ }
134
+ /** A value a setting was given, and where it came from. */
135
+ export interface ExplainGiven {
136
+ /** as JSON, a duration spelled, a secret as *** */
137
+ readonly value: string;
138
+ readonly from: ExplainOrigin;
124
139
  }
140
+ /**
141
+ * Where a value came from: the declaration, a layer in the list by its place,
142
+ * the declaration 1, a file, a variable, or a change. `String(origin)` is the
143
+ * text a line's `from` says: `the declaration`, `layer 2`, `app.yaml`,
144
+ * `APP_PORT in .env`, `a change, version 7, 2026-10-13 14:03:05 UTC`. A kind
145
+ * from a newer server is kept as it was sent, and its text is the kind.
146
+ */
147
+ export type ExplainOrigin = {
148
+ readonly kind: 'declaration';
149
+ } | {
150
+ readonly kind: 'layer';
151
+ readonly place: number;
152
+ } | {
153
+ readonly kind: 'file';
154
+ readonly path: string;
155
+ } | {
156
+ readonly kind: 'env';
157
+ readonly variable: string;
158
+ /** the .env file that set the variable */
159
+ readonly dotenv?: string;
160
+ /** the file a NAME_FILE variable named */
161
+ readonly file?: string;
162
+ } | {
163
+ readonly kind: 'change';
164
+ readonly version: number;
165
+ readonly at: Date;
166
+ };
125
167
  /** Every setting's line, for console.table, and what was read and not used. */
126
168
  export type Explained = readonly ExplainLine[] & {
127
169
  readonly notes: readonly string[];
@@ -193,6 +235,9 @@ export declare function env(prefix: string, options?: EnvOptions): EnvLayer;
193
235
  * 'APP', 'limits.maxRps' → APP_LIMITS_MAX_RPS
194
236
  */
195
237
  export declare function envName(prefix: string, path: string): string;
238
+ type SentOrigin = Read<typeof ConfigOrigin.fields>;
239
+ /** Where a value came from, only the fields its kind names, its text the core's `from`. */
240
+ export declare function explainOrigin(sent: SentOrigin): ExplainOrigin;
196
241
  /**
197
242
  * A program's settings as one typed value, read from memory: open one with
198
243
  * `store.config(name, [declaration, ...layers])`.
@@ -220,7 +265,10 @@ export declare class Config<D> {
220
265
  * before it, made in this process or another. It returns the call that stops it.
221
266
  */
222
267
  watch(watcher: (next: Value<D>, previous: Value<D> | undefined) => void): () => void;
223
- /** Every setting with its value, the layer that gave it and what it went over. */
268
+ /**
269
+ * Every setting with its value, the layer that gave it and what it went
270
+ * over, as text, and in `given` as data.
271
+ */
224
272
  explain(): Explained;
225
273
  /**
226
274
  * Stops following the config: the store closes. It resolves once the
package/dist/config.js CHANGED
@@ -8,6 +8,7 @@
8
8
  // on one stream that every handle and watcher of it in the process shares.
9
9
  import { readFile } from 'node:fs/promises';
10
10
  import { CancelledError, ConflictError, InvalidError, UnavailableError } from './errors.js';
11
+ import { unsent } from './handles.js';
11
12
  import { check, isSchema } from './schema.js';
12
13
  import { ConnectionLostError } from './session.js';
13
14
  import { ms, spelled } from './time.js';
@@ -403,6 +404,84 @@ function merged(value, changes) {
403
404
  }
404
405
  return out;
405
406
  }
407
+ /**
408
+ * A line as the store sent it. `given` is not enumerable, so that
409
+ * `console.table(config.explain())` shows the four columns it always showed,
410
+ * and toJSON gives it back to JSON.stringify.
411
+ */
412
+ function explainLine(line) {
413
+ const shown = {
414
+ path: line.path ?? '',
415
+ value: line.value ?? '',
416
+ from: line.from ?? '',
417
+ over: (line.over ?? []).join(', '),
418
+ };
419
+ const given = (line.given ?? []).map(each => ({
420
+ value: each.value ?? '',
421
+ from: explainOrigin(each.from ?? {}),
422
+ }));
423
+ const json = {
424
+ toJSON() {
425
+ return { ...shown, given };
426
+ },
427
+ };
428
+ return Object.defineProperties(shown, {
429
+ given: { value: given },
430
+ toJSON: { value: json.toJSON },
431
+ });
432
+ }
433
+ const originMethods = {
434
+ toString() {
435
+ return originText(this);
436
+ },
437
+ };
438
+ /** Where a value came from, only the fields its kind names, its text the core's `from`. */
439
+ export function explainOrigin(sent) {
440
+ return Object.defineProperty(originOf(sent), 'toString', { value: originMethods.toString });
441
+ }
442
+ function originOf(sent) {
443
+ switch (sent.kind) {
444
+ case 'layer':
445
+ return { kind: 'layer', place: sent.place ?? 0 };
446
+ case 'file':
447
+ return { kind: 'file', path: sent.path ?? '' };
448
+ case 'env':
449
+ return {
450
+ kind: 'env',
451
+ variable: sent.variable ?? '',
452
+ ...(sent.dotenv === undefined ? {} : { dotenv: sent.dotenv }),
453
+ ...(sent.file === undefined ? {} : { file: sent.file }),
454
+ };
455
+ case 'change':
456
+ return { kind: 'change', version: sent.version ?? 0, at: new Date(sent.at ?? 0) };
457
+ case 'declaration':
458
+ case undefined:
459
+ return { kind: 'declaration' };
460
+ default:
461
+ // a kind from a newer server, kept as it was sent
462
+ return { kind: sent.kind };
463
+ }
464
+ }
465
+ /** The text the core's `from` says: crates/tinystore/src/kv/config/explain.rs, Origin's Display. */
466
+ function originText(origin) {
467
+ switch (origin.kind) {
468
+ case 'declaration':
469
+ return 'the declaration';
470
+ case 'layer':
471
+ return `layer ${origin.place}`;
472
+ case 'file':
473
+ return origin.path;
474
+ case 'env':
475
+ if (origin.dotenv !== undefined) {
476
+ return `${origin.variable} in ${origin.dotenv}`;
477
+ }
478
+ return origin.file === undefined ? origin.variable : `${origin.variable}, ${origin.file}`;
479
+ case 'change':
480
+ return `a change, version ${origin.version}, ${origin.at.toISOString().slice(0, 19).replace('T', ' ')} UTC`;
481
+ }
482
+ // a kind from a newer server says itself
483
+ return origin.kind;
484
+ }
406
485
  /**
407
486
  * A program's settings as one typed value, read from memory: open one with
408
487
  * `store.config(name, [declaration, ...layers])`.
@@ -505,7 +584,10 @@ export class Config {
505
584
  this.#watchers.delete(watcher);
506
585
  };
507
586
  }
508
- /** Every setting with its value, the layer that gave it and what it went over. */
587
+ /**
588
+ * Every setting with its value, the layer that gave it and what it went
589
+ * over, as text, and in `given` as data.
590
+ */
509
591
  explain() {
510
592
  const refused = this.#refused === undefined ? [] : [`a value validate refused: ${this.#refused.message}`];
511
593
  return Object.assign([...this.#lines], { notes: [...this.#notes, ...refused] });
@@ -540,6 +622,8 @@ export class Config {
540
622
  const opened = ConfigValue.decode(body);
541
623
  await this.#take(opened);
542
624
  return opened.handle ?? 0;
625
+ }, (err) => {
626
+ throw unsent(err);
543
627
  });
544
628
  this.#handles.set(connection, handle);
545
629
  handle.catch(() => this.#handles.delete(connection));
@@ -571,12 +655,7 @@ export class Config {
571
655
  this.#refused = undefined;
572
656
  this.#value = next;
573
657
  this.#version = version;
574
- this.#lines = (answer.lines ?? []).map(line => ({
575
- path: line.path ?? '',
576
- value: line.value ?? '',
577
- from: line.from ?? '',
578
- over: (line.over ?? []).join(', '),
579
- }));
658
+ this.#lines = (answer.lines ?? []).map(explainLine);
580
659
  this.#notes = answer.notes ?? [];
581
660
  for (const wake of this.#newer.splice(0)) {
582
661
  wake();
@@ -6,12 +6,16 @@ import type { NodeOptions } from './store.ts';
6
6
  * one database:
7
7
  *
8
8
  * 'full' synced to the disk: it survives a crash of the operating
9
- * system and a power loss. What every file is unless told.
9
+ * system and a power loss. What kv, jobs, files, search and
10
+ * every database are unless told.
10
11
  * 'os' written to the operating system, synced a little later: it
11
12
  * survives the program's crash, and a power loss may take the
12
- * last commits, never the file.
13
+ * last commits, never the file. What records and metrics are
14
+ * unless told.
13
15
  */
14
16
  export type Durability = 'full' | 'os';
17
+ /** Refuses a count of series no store can hold, before anything leaves. */
18
+ export declare function checkMaxSeries(maxSeries: number | undefined): void;
15
19
  /** Refuses a durability that is neither word, before anything leaves. */
16
20
  export declare function checkDurability(durability: Durability | undefined, of: string): void;
17
21
  /**
@@ -28,21 +32,34 @@ export declare class Connection {
28
32
  /** the handle each open was answered, once it was: what a call made in place reads without waiting */
29
33
  readonly opened: Map<object, number>;
30
34
  constructor(session: Session, transport: Transport, closing?: () => Promise<unknown>);
31
- /** Connects, shakes hands, and gives up after the handshake's time. */
32
- static dial(runtime: Runtime, endpoint: string, options: SessionOptions, tls?: TlsOptions): Promise<Connection>;
35
+ /**
36
+ * Connects, shakes hands, and gives up after the handshake's time, or once
37
+ * the signal aborts: before the socket connects, its connect is let go, and
38
+ * after, the socket.
39
+ */
40
+ static dial(runtime: Runtime, endpoint: string, options: SessionOptions, tls?: TlsOptions, signal?: AbortSignal): Promise<Connection>;
33
41
  /** Shakes hands over a pipe to the core in this process. */
34
- static overPipe(session: Session, transport: Transport): Promise<Connection>;
42
+ static overPipe(session: Session, transport: Transport, signal?: AbortSignal): Promise<Connection>;
35
43
  /**
36
44
  * Shakes hands over a private child's stdin and stdout. Closing waits for
37
45
  * the child's exit, since until then it holds the directory: its LOCK, and
38
46
  * on Windows every file it opened, which a removal fails on.
39
47
  */
40
- static overChild(child: PrivateChild, session: Session): Promise<Connection>;
48
+ static overChild(child: PrivateChild, session: Session, signal?: AbortSignal): Promise<Connection>;
41
49
  /** Ends the connection; a private child is waited for until it has exited. */
42
50
  close(): Promise<void>;
43
51
  }
52
+ /**
53
+ * What a dial is given: a cancel of its own, which only its link's close
54
+ * aborts, never a caller's, and where it says what it waits for, which a
55
+ * caller who gives up on it is told.
56
+ */
57
+ export interface Dialling {
58
+ readonly signal: AbortSignal;
59
+ waiting(what: string): void;
60
+ }
44
61
  /** Where a link dials. */
45
- export type Dialer = () => Promise<Connection>;
62
+ export type Dialer = (dialling: Dialling) => Promise<Connection>;
46
63
  /**
47
64
  * Finds the directory's sidecar through SERVE or starts one, as docs/wire.md
48
65
  * "Finding a local server" says: a sidecar found proves itself before the
@@ -63,6 +80,8 @@ export interface Started {
63
80
  node?: NodeOptions | undefined;
64
81
  /** measures the store into its own metrics, the machine too unless it says system: false */
65
82
  selfMetrics?: SelfMetrics | undefined;
83
+ /** the metrics series the store holds at most, when not the store's own 100,000 */
84
+ maxSeries?: number | undefined;
66
85
  }
67
86
  /**
68
87
  * What a store measures of itself: `true` its commits, files and memory and
@@ -71,6 +90,12 @@ export interface Started {
71
90
  export type SelfMetrics = boolean | {
72
91
  system?: boolean;
73
92
  };
93
+ /**
94
+ * Why a sidecar that never served stopped: the last lines it wrote to
95
+ * stderr, which say a failure before its log opened, or else the lines its
96
+ * log gained since it started, when it was `logged` bytes long.
97
+ */
98
+ export declare function startFailure(stderr: string, log: Uint8Array | undefined, logged: number): string;
74
99
  /**
75
100
  * Whether a server's release is older than the SDK's own; a build that is no
76
101
  * release, a development copy's or a Go pseudo-version, is neither.
@@ -100,8 +125,12 @@ export type Idempotence = 'read' | 'write';
100
125
  export declare class Link {
101
126
  #private;
102
127
  constructor(dial: Dialer);
103
- /** The connection a call goes on. */
104
- connection(): Promise<Connection>;
128
+ /**
129
+ * The connection a call goes on. A caller whose signal aborts stops
130
+ * waiting at once, CancelledError naming what the dial waits for, and
131
+ * the dial goes on for the others.
132
+ */
133
+ connection(signal?: AbortSignal, of?: string): Promise<Connection>;
105
134
  /** The connection a call goes on, when one is there to take it without waiting. */
106
135
  ready(): Connection | undefined;
107
136
  /**
@@ -109,7 +138,20 @@ export declare class Link {
109
138
  * that connection, whose handles it may open; run sends it.
110
139
  */
111
140
  run<T>(idempotence: Idempotence, attempt: (connection: Connection) => Promise<T>, signal?: AbortSignal): Promise<T>;
112
- /** Closes the connection and every one to come. */
141
+ /**
142
+ * Keeps a stream that follows the store until it closes, a subscription's,
143
+ * a loop's, a tail's or a watch's, for close to cancel; it returns what
144
+ * lets the stream go. Once the link is closed it cancels the stream at
145
+ * once.
146
+ */
147
+ follow(stream: Stream): () => void;
148
+ /**
149
+ * Closes the connection and every one to come. Each stream that follows
150
+ * the store is cancelled first, and its end waited for, a moment at most:
151
+ * one the server still ran would keep a private child, or a sidecar's
152
+ * connection, draining for ten seconds. A dial under way stops at its next
153
+ * wait, and every call waiting on it fails ClosedError.
154
+ */
113
155
  close(): Promise<void>;
114
156
  }
115
157
  /**