@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/store.d.ts CHANGED
@@ -43,6 +43,11 @@ export interface OpenOptions {
43
43
  * unless asked for; a sidecar found running keeps its own.
44
44
  */
45
45
  selfMetrics?: SelfMetrics;
46
+ /**
47
+ * The metrics series the store holds at most: a new series past them is
48
+ * a LimitError. 100,000 unless given; a sidecar found running keeps its own.
49
+ */
50
+ maxSeries?: number;
46
51
  /** The tinystore binary: TINYSTORE_BIN, this platform's package, or PATH's when absent. */
47
52
  binary?: string;
48
53
  /**
@@ -57,12 +62,14 @@ export interface OpenOptions {
57
62
  */
58
63
  clock?: Time;
59
64
  /**
60
- * How far a commit of the store's files goes before it returns: `'full'`
61
- * unless given. `'os'` does not wait for the disk, so a write returns in
62
- * microseconds, survives this program's crash, and may be lost with the
63
- * last others to a power loss. It is the store's, set by whoever opens it
64
- * first: a sidecar found running with another is refused. A database may
65
- * say its own, `store.database('audit', { durability: 'full' })`.
65
+ * How far a commit of the store's files goes before it returns. Unless
66
+ * given, kv, jobs, files, search and every database commit `'full'`, and
67
+ * records and metrics `'os'`; given, every file commits so. `'os'` does
68
+ * not wait for the disk, so a write returns in microseconds, survives this
69
+ * program's crash, and may be lost with the last others to a power loss.
70
+ * It is the store's, set by whoever opens it first: a sidecar found
71
+ * running with another, or with none when this asks one, is refused. A
72
+ * database may say its own, `store.database('audit', { durability: 'full' })`.
66
73
  */
67
74
  durability?: Durability;
68
75
  /**
@@ -303,9 +310,11 @@ export declare class Store implements AsyncDisposable {
303
310
  /**
304
311
  * Stops every worker, each once its handlers under way have answered,
305
312
  * ingests the instruments' last values, hands over the loggers' lines and
306
- * cancels every config's stream, then closes the connection. A private child is waited for until it has
307
- * exited, so that the directory is free once this returns; the directory's
308
- * sidecar goes once it has been idle.
313
+ * cancels every config's stream, then every subscription, `each` loop,
314
+ * tail and watch, whose loops end `ClosedError`, and closes the
315
+ * connection. A private child is waited for until it has exited, so that
316
+ * the directory is free once this returns; the directory's sidecar goes
317
+ * once it has been idle.
309
318
  */
310
319
  close(): Promise<void>;
311
320
  [Symbol.asyncDispose](): Promise<void>;
@@ -313,13 +322,18 @@ export declare class Store implements AsyncDisposable {
313
322
  /**
314
323
  * Opens the store in a directory through its sidecar, found through SERVE or
315
324
  * started, or through a private child when asked. It returns once the server
316
- * has answered, so that a directory that cannot be served fails here.
325
+ * has answered, so that a directory that cannot be served fails here. Under
326
+ * withSignal it stops waiting once the signal aborts, CancelledError saying
327
+ * what it waited for, and keeps no connection:
328
+ *
329
+ * const store = await withSignal(AbortSignal.timeout(2000), () => open('./data'))
317
330
  */
318
331
  export declare function open(dir: string, options?: OpenOptions): Promise<Store>;
319
332
  export declare function openWith(runtime: Runtime, dir: string, options?: OpenOptions): Promise<Store>;
320
333
  /**
321
334
  * Connects to a remote server: tls:// checks the server's certificate before
322
335
  * the token leaves; tcp:// sends the token in the clear, for a network its
323
- * operator trusts.
336
+ * operator trusts. Under withSignal it stops waiting once the signal aborts,
337
+ * as open does.
324
338
  */
325
339
  export declare function connect(url: string, options: ConnectOptions): Promise<Store>;
package/dist/store.js CHANGED
@@ -1,9 +1,12 @@
1
+ import { statSync } from 'node:fs';
2
+ import { dirname, resolve } from 'node:path';
1
3
  import { backup } from './backup.js';
2
4
  import { openFiles } from './blobs.js';
5
+ import { currentSignal } from './cancel.js';
3
6
  import { Channel } from './channels.js';
4
7
  import { Clock } from './clock.js';
5
8
  import { Config } from './config.js';
6
- import { asking, checkDurability, embedded, Link, privateChild, remote, sidecar, } from './connection.js';
9
+ import { asking, checkDurability, checkMaxSeries, embedded, Link, privateChild, remote, sidecar, } from './connection.js';
7
10
  import { ClosedError, InvalidError } from './errors.js';
8
11
  import { Instruments } from './instruments.js';
9
12
  import { openQueue, openSchedule, } from './jobs.js';
@@ -258,9 +261,11 @@ export class Store {
258
261
  /**
259
262
  * Stops every worker, each once its handlers under way have answered,
260
263
  * ingests the instruments' last values, hands over the loggers' lines and
261
- * cancels every config's stream, then closes the connection. A private child is waited for until it has
262
- * exited, so that the directory is free once this returns; the directory's
263
- * sidecar goes once it has been idle.
264
+ * cancels every config's stream, then every subscription, `each` loop,
265
+ * tail and watch, whose loops end `ClosedError`, and closes the
266
+ * connection. A private child is waited for until it has exited, so that
267
+ * the directory is free once this returns; the directory's sidecar goes
268
+ * once it has been idle.
264
269
  */
265
270
  async close() {
266
271
  this.#closing = true;
@@ -289,7 +294,11 @@ const runtime = typeof Bun === 'undefined' ? nodeRuntime : bunRuntime;
289
294
  /**
290
295
  * Opens the store in a directory through its sidecar, found through SERVE or
291
296
  * started, or through a private child when asked. It returns once the server
292
- * has answered, so that a directory that cannot be served fails here.
297
+ * has answered, so that a directory that cannot be served fails here. Under
298
+ * withSignal it stops waiting once the signal aborts, CancelledError saying
299
+ * what it waited for, and keeps no connection:
300
+ *
301
+ * const store = await withSignal(AbortSignal.timeout(2000), () => open('./data'))
293
302
  */
294
303
  export async function open(dir, options = {}) {
295
304
  return openWith(runtime, dir, options);
@@ -304,11 +313,13 @@ export async function openWith(runtime, dir, options = {}) {
304
313
  const clock = options.clock === undefined ? undefined : new Date(unixMs(options.clock));
305
314
  const durability = options.durability;
306
315
  checkDurability(durability, 'open');
316
+ checkMaxSeries(options.maxSeries);
307
317
  const started = {
308
318
  durability,
309
319
  encryptionKeyFile: options.encryptionKeyFile,
310
320
  node: options.node,
311
321
  selfMetrics: options.selfMetrics,
322
+ maxSeries: options.maxSeries,
312
323
  };
313
324
  const dial = options.embedded === true
314
325
  ? embedded(runtime, dir, () => findLibrary(runtime, options.library), started)
@@ -316,24 +327,42 @@ export async function openWith(runtime, dir, options = {}) {
316
327
  ? privateChild(runtime, dir, binary, clock, started)
317
328
  : sidecar(runtime, dir, binary, { idle, ...started });
318
329
  const link = new Link(asking(dial, dir, durability));
319
- await link.connection();
330
+ await reached(link, `open ${dir}`);
320
331
  return new Store(link);
321
332
  }
322
333
  /**
323
334
  * Connects to a remote server: tls:// checks the server's certificate before
324
335
  * the token leaves; tcp:// sends the token in the clear, for a network its
325
- * operator trusts.
336
+ * operator trusts. Under withSignal it stops waiting once the signal aborts,
337
+ * as open does.
326
338
  */
327
339
  export async function connect(url, options) {
328
340
  const link = new Link(remote(runtime, url, options.token, options.tls));
329
- await link.connection();
341
+ await reached(link, `connect ${url}`);
330
342
  return new Store(link);
331
343
  }
344
+ /**
345
+ * Waits for the link's first connection under the caller's signal. A caller
346
+ * who gives up, or a dial that fails, closes the link, which stops the dial
347
+ * and closes what it made.
348
+ */
349
+ async function reached(link, of) {
350
+ try {
351
+ await link.connection(currentSignal(), of);
352
+ }
353
+ catch (err) {
354
+ await link.close();
355
+ throw err;
356
+ }
357
+ }
332
358
  // two letters or more before a colon: an address, never a Windows drive
333
359
  const address = /^([a-z][a-z0-9+.-]+):/i;
334
360
  /**
335
361
  * Refuses an address where a directory belongs: open('tcp://…') would make a
336
- * folder of that name and start a server in it, rather than reach the one meant.
362
+ * folder of that name and start a server in it, rather than reach the one
363
+ * meant. Refuses a directory that is a file, or sits under one, in the core's
364
+ * words, before a server starts or the core loads, so that every way says it
365
+ * alike.
337
366
  *
338
367
  * open('tcp://db.internal:7070') → use connect
339
368
  * open('pipe:tinystore-d761f24b7e59') → open the directory it serves
@@ -347,6 +376,35 @@ function checkDirectory(dir) {
347
376
  if (scheme !== undefined) {
348
377
  throw new InvalidError(`open takes a store's directory, and ${dir} is an address: open the directory its server serves, and it is found through SERVE`);
349
378
  }
379
+ const absolute = resolve(dir);
380
+ const file = fileInTheWay(absolute);
381
+ if (file === absolute) {
382
+ throw new InvalidError(`store ${absolute} is a file, not a directory`);
383
+ }
384
+ if (file !== undefined) {
385
+ throw new InvalidError(`store ${absolute}: ${file} is a file, not a directory`);
386
+ }
387
+ }
388
+ /**
389
+ * The first of a directory and the folders above it that is there, when it
390
+ * is a file: what keeps the directory from being made.
391
+ */
392
+ function fileInTheWay(dir) {
393
+ for (let path = dir;; path = dirname(path)) {
394
+ let found;
395
+ try {
396
+ found = statSync(path);
397
+ }
398
+ catch {
399
+ found = undefined;
400
+ }
401
+ if (found !== undefined) {
402
+ return found.isDirectory() ? undefined : path;
403
+ }
404
+ if (dirname(path) === path) {
405
+ return undefined;
406
+ }
407
+ }
350
408
  }
351
409
  function findBinary(runtime, given) {
352
410
  const executable = runtime.windows ? 'tinystore.exe' : 'tinystore';
@@ -101,6 +101,11 @@ export declare class Message<F extends Fields> implements Codec<Read<F>, Written
101
101
  encode(value: Written<F>): Uint8Array;
102
102
  /** Reads a body that is this message and nothing after it. */
103
103
  decode(body: Uint8Array): Read<F>;
104
+ /**
105
+ * Reads a body as `decode` does, for a body nothing else holds: its bins
106
+ * are views of it rather than copies, as a file's bytes are of a get's.
107
+ */
108
+ view(body: Uint8Array): Read<F>;
104
109
  }
105
110
  export declare function message<const F extends Fields>(name: string, fields: F, made?: Made<NoInfer<F>>): Message<F>;
106
111
  export {};
@@ -386,6 +386,16 @@ export class Message {
386
386
  r.end();
387
387
  return value;
388
388
  }
389
+ /**
390
+ * Reads a body as `decode` does, for a body nothing else holds: its bins
391
+ * are views of it rather than copies, as a file's bytes are of a get's.
392
+ */
393
+ view(body) {
394
+ const r = new Reader(body, 0, body.length, true);
395
+ const value = this.read(r);
396
+ r.end();
397
+ return value;
398
+ }
389
399
  #read(r) {
390
400
  const read = {};
391
401
  r.fields(key => {
@@ -27,6 +27,8 @@ export interface Header {
27
27
  export declare function kindName(kind: number): string;
28
28
  /** Reads a header from its twelve bytes without checking it. */
29
29
  export declare function parseHeader(bytes: Uint8Array, at?: number): Header;
30
+ /** The body's length a header at `at` says, its twelve bytes there and not checked. */
31
+ export declare function bodyLength(bytes: Uint8Array, at?: number): number;
30
32
  /** Writes a header where its twelve bytes were kept, once its body's length is known. */
31
33
  export declare function putHeader(bytes: Uint8Array, at: number, kind: number, flags: number, method: number, stream: number, length: number): void;
32
34
  /**
@@ -47,6 +47,10 @@ export function parseHeader(bytes, at = 0) {
47
47
  stream: uint32At(bytes, at + 8),
48
48
  };
49
49
  }
50
+ /** The body's length a header at `at` says, its twelve bytes there and not checked. */
51
+ export function bodyLength(bytes, at = 0) {
52
+ return uint32At(bytes, at);
53
+ }
50
54
  /** Writes a header where its twelve bytes were kept, once its body's length is known. */
51
55
  export function putHeader(bytes, at, kind, flags, method, stream, length) {
52
56
  putUint32(bytes, at, length);
@@ -73,8 +73,12 @@ export declare function typeOf(b: number): Type;
73
73
  */
74
74
  export declare class Reader {
75
75
  #private;
76
- /** Reads a message that is the bytes from `at` to `end`: all of them unless said. */
77
- constructor(bytes: Uint8Array, at?: number, end?: number);
76
+ /**
77
+ * Reads a message that is the bytes from `at` to `end`: all of them unless
78
+ * said. With `views`, the bytes are the reader's alone, and the bins it
79
+ * reads keep them rather than copy them.
80
+ */
81
+ constructor(bytes: Uint8Array, at?: number, end?: number, views?: boolean);
78
82
  /** Turns to another message, for a reader kept from one answer to the next. */
79
83
  reset(bytes: Uint8Array, at: number, end: number): void;
80
84
  /** Refuses bytes left after the one value a message is. */
@@ -107,7 +111,7 @@ export declare class Reader {
107
111
  str(): string;
108
112
  /** Reads a bin as a view of the body; an empty one is an empty array. */
109
113
  bin(): Uint8Array;
110
- /** Reads a bin as bytes of its own, which outlive the body. */
114
+ /** Reads a bin as bytes of its own, which outlive the body: a view where the body is the reader's. */
111
115
  bytes(): Uint8Array;
112
116
  /**
113
117
  * Reads an array's count and enters it; leave once its elements are read.
@@ -436,11 +436,18 @@ export class Reader {
436
436
  #seen = new Array(maxDepth + 1).fill(0);
437
437
  /** The numbers past those, rare enough to be kept in a set, made when one comes. */
438
438
  #others = [];
439
- /** Reads a message that is the bytes from `at` to `end`: all of them unless said. */
440
- constructor(bytes, at = 0, end = bytes.length) {
439
+ /** Whether `bytes()` gives views of the bytes, which nothing else holds, rather than copies. */
440
+ #views;
441
+ /**
442
+ * Reads a message that is the bytes from `at` to `end`: all of them unless
443
+ * said. With `views`, the bytes are the reader's alone, and the bins it
444
+ * reads keep them rather than copy them.
445
+ */
446
+ constructor(bytes, at = 0, end = bytes.length, views = false) {
441
447
  this.#bytes = bytes;
442
448
  this.#at = at;
443
449
  this.#end = end;
450
+ this.#views = views;
444
451
  }
445
452
  /** Turns to another message, for a reader kept from one answer to the next. */
446
453
  reset(bytes, at, end) {
@@ -692,11 +699,11 @@ export class Reader {
692
699
  const at = this.#take(n);
693
700
  return this.#bytes.subarray(at, at + n);
694
701
  }
695
- /** Reads a bin as bytes of its own, which outlive the body. */
702
+ /** Reads a bin as bytes of its own, which outlive the body: a view where the body is the reader's. */
696
703
  bytes() {
697
704
  const n = this.#binLength();
698
705
  const at = this.#take(n);
699
- return this.#bytes.slice(at, at + n);
706
+ return this.#views ? this.#bytes.subarray(at, at + n) : this.#bytes.slice(at, at + n);
700
707
  }
701
708
  #binLength() {
702
709
  const b = this.#next();