@tinyshed/tinystore 0.1.0-rc.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 (100) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +262 -0
  3. package/bin/tinystore.js +50 -0
  4. package/dist/background.d.ts +30 -0
  5. package/dist/background.js +93 -0
  6. package/dist/blobs.d.ts +98 -0
  7. package/dist/blobs.js +299 -0
  8. package/dist/cancel.d.ts +14 -0
  9. package/dist/cancel.js +22 -0
  10. package/dist/clock.d.ts +21 -0
  11. package/dist/clock.js +35 -0
  12. package/dist/config.d.ts +60 -0
  13. package/dist/config.js +417 -0
  14. package/dist/connection.d.ts +78 -0
  15. package/dist/connection.js +405 -0
  16. package/dist/console.d.ts +48 -0
  17. package/dist/console.js +195 -0
  18. package/dist/errors.d.ts +103 -0
  19. package/dist/errors.js +158 -0
  20. package/dist/handles.d.ts +28 -0
  21. package/dist/handles.js +37 -0
  22. package/dist/index.d.ts +21 -0
  23. package/dist/index.js +7 -0
  24. package/dist/jobs.d.ts +304 -0
  25. package/dist/jobs.js +684 -0
  26. package/dist/kv.d.ts +283 -0
  27. package/dist/kv.js +815 -0
  28. package/dist/limiter.d.ts +45 -0
  29. package/dist/limiter.js +68 -0
  30. package/dist/logger.d.ts +96 -0
  31. package/dist/logger.js +243 -0
  32. package/dist/metrics.d.ts +249 -0
  33. package/dist/metrics.js +610 -0
  34. package/dist/once.d.ts +31 -0
  35. package/dist/once.js +116 -0
  36. package/dist/quota.d.ts +44 -0
  37. package/dist/quota.js +98 -0
  38. package/dist/records.d.ts +182 -0
  39. package/dist/records.js +346 -0
  40. package/dist/runtime/bun.d.ts +2 -0
  41. package/dist/runtime/bun.js +164 -0
  42. package/dist/runtime/node.d.ts +2 -0
  43. package/dist/runtime/node.js +157 -0
  44. package/dist/runtime/shared.d.ts +25 -0
  45. package/dist/runtime/shared.js +45 -0
  46. package/dist/runtime.d.ts +48 -0
  47. package/dist/runtime.js +4 -0
  48. package/dist/schema.d.ts +39 -0
  49. package/dist/schema.js +21 -0
  50. package/dist/session.d.ts +120 -0
  51. package/dist/session.js +546 -0
  52. package/dist/sql.d.ts +121 -0
  53. package/dist/sql.js +342 -0
  54. package/dist/store.d.ts +103 -0
  55. package/dist/store.js +153 -0
  56. package/dist/time.d.ts +35 -0
  57. package/dist/time.js +44 -0
  58. package/dist/trace.d.ts +18 -0
  59. package/dist/trace.js +22 -0
  60. package/dist/wire/codec.d.ts +90 -0
  61. package/dist/wire/codec.js +383 -0
  62. package/dist/wire/frame.d.ts +41 -0
  63. package/dist/wire/frame.js +102 -0
  64. package/dist/wire/messages.d.ts +1403 -0
  65. package/dist/wire/messages.js +472 -0
  66. package/dist/wire/msgpack.d.ts +93 -0
  67. package/dist/wire/msgpack.js +680 -0
  68. package/package.json +40 -0
  69. package/src/background.ts +108 -0
  70. package/src/blobs.ts +437 -0
  71. package/src/cancel.ts +26 -0
  72. package/src/clock.ts +45 -0
  73. package/src/config.ts +501 -0
  74. package/src/connection.ts +512 -0
  75. package/src/console.ts +228 -0
  76. package/src/errors.ts +211 -0
  77. package/src/handles.ts +68 -0
  78. package/src/index.ts +92 -0
  79. package/src/jobs.ts +963 -0
  80. package/src/kv.ts +1093 -0
  81. package/src/limiter.ts +99 -0
  82. package/src/logger.ts +326 -0
  83. package/src/metrics.ts +896 -0
  84. package/src/once.ts +142 -0
  85. package/src/quota.ts +137 -0
  86. package/src/records.ts +537 -0
  87. package/src/runtime/bun.ts +190 -0
  88. package/src/runtime/node.ts +177 -0
  89. package/src/runtime/shared.ts +61 -0
  90. package/src/runtime.ts +57 -0
  91. package/src/schema.ts +69 -0
  92. package/src/session.ts +665 -0
  93. package/src/sql.ts +478 -0
  94. package/src/store.ts +219 -0
  95. package/src/time.ts +87 -0
  96. package/src/trace.ts +32 -0
  97. package/src/wire/codec.ts +445 -0
  98. package/src/wire/frame.ts +139 -0
  99. package/src/wire/messages.ts +562 -0
  100. package/src/wire/msgpack.ts +712 -0
@@ -0,0 +1,45 @@
1
+ // What Bun's runtime and Node's do alike: an endpoint read into an address, a
2
+ // sidecar started through node:child_process, which both implement, and the
3
+ // last lines of a child's stderr.
4
+ import { spawn } from 'node:child_process';
5
+ import { ClosedError } from '../errors.js';
6
+ export function address(endpoint) {
7
+ if (endpoint.startsWith('unix://')) {
8
+ return { kind: 'unix', path: endpoint.slice('unix://'.length) };
9
+ }
10
+ if (endpoint.startsWith('pipe:')) {
11
+ return { kind: 'pipe', path: `\\\\.\\pipe\\${endpoint.slice('pipe:'.length)}` };
12
+ }
13
+ const remote = /^(tcp|tls):\/\/(\[[^\]]+\]|[^:/]+):(\d+)$/.exec(endpoint);
14
+ if (remote === null) {
15
+ throw new ClosedError(`no transport for the endpoint ${endpoint}`);
16
+ }
17
+ const host = remote[2].replace(/^\[|\]$/g, '');
18
+ return { kind: remote[1], host, port: Number(remote[3]) };
19
+ }
20
+ /**
21
+ * Starts a sidecar that outlives this process, through node:child_process in
22
+ * Bun too, since Bun.spawn starts no process that outlives a Ctrl-C of its
23
+ * parent's group.
24
+ */
25
+ export function spawnDetached(argv) {
26
+ const child = spawn(argv[0], argv.slice(1), {
27
+ detached: true,
28
+ stdio: 'ignore',
29
+ windowsHide: true,
30
+ });
31
+ const exited = new Promise(resolve => {
32
+ child.once('exit', code => resolve(code ?? -1));
33
+ child.once('error', () => resolve(-1));
34
+ });
35
+ child.unref();
36
+ return { exited, kill: () => child.kill() };
37
+ }
38
+ /** How much of a child's stderr is kept, its last lines, to say why it ended. */
39
+ export const stderrKept = 16 << 10;
40
+ export function lastLines(text, n = 5) {
41
+ return text.trimEnd().split('\n').slice(-n).join('\n');
42
+ }
43
+ export function exitedWith(code, stderr) {
44
+ return new ClosedError(`the private server exited with ${code}${stderr === '' ? '' : `: ${lastLines(stderr)}`}`);
45
+ }
@@ -0,0 +1,48 @@
1
+ /** What a transport tells the session reading it. */
2
+ export interface TransportEvents {
3
+ data(bytes: Uint8Array): void;
4
+ /** the stream ended, cleanly or not; called once */
5
+ end(err: Error): void;
6
+ }
7
+ /** A byte stream to a server: a socket, a pipe, or a child's stdin and stdout. */
8
+ export interface Transport {
9
+ /** Writes bytes whole and in order; what the stream does not take yet waits for it. */
10
+ write(bytes: Uint8Array): void;
11
+ /** Ends the stream: a socket's close, or a child's stdin, which is its end. */
12
+ close(): void;
13
+ }
14
+ export interface TlsOptions {
15
+ /** the certificates to trust besides the system's, PEM */
16
+ ca?: string | string[];
17
+ /** the name the certificate must carry, the endpoint's host when absent */
18
+ serverName?: string;
19
+ }
20
+ /** A process the SDK started. */
21
+ export interface Child {
22
+ /** its exit code once it has exited */
23
+ readonly exited: Promise<number>;
24
+ kill(): void;
25
+ }
26
+ /** A private server: a child whose stdin and stdout are the connection. */
27
+ export interface PrivateChild extends Child {
28
+ readonly transport: Transport;
29
+ /** the last lines it wrote to stderr, which say why it ended */
30
+ stderr(): string;
31
+ }
32
+ export interface Runtime {
33
+ /** a name and version for the server's logs: tinystore-js on bun/1.4.2 */
34
+ readonly client: string;
35
+ readonly windows: boolean;
36
+ /** Connects to an endpoint: unix://path, pipe:name, tcp://host:port or tls://host:port. */
37
+ connect(endpoint: string, events: TransportEvents, tls?: TlsOptions): Promise<Transport>;
38
+ /** Starts a private server whose stdin and stdout carry the frames. */
39
+ spawnPrivate(argv: string[], events: TransportEvents): PrivateChild;
40
+ /** Starts a process that outlives this one, with no stdio to read. */
41
+ spawnDetached(argv: string[]): Child;
42
+ /** A file's bytes, opened, read and closed at once; undefined when it is not there. */
43
+ readFile(path: string): Promise<Uint8Array | undefined>;
44
+ /** The executable a name finds on PATH. */
45
+ which(name: string): string | undefined;
46
+ /** The server binary a package of this runtime carries for this platform. */
47
+ packagedBinary(): string | undefined;
48
+ }
@@ -0,0 +1,4 @@
1
+ // What the SDK needs of the runtime it runs in: a byte stream to a server, a
2
+ // child process, a file, a random byte. Everything else is plain TypeScript
3
+ // over Uint8Array, so a runtime other than Bun is one file implementing this.
4
+ export {};
@@ -0,0 +1,39 @@
1
+ /** A schema that checks a value and may give back one of another type. */
2
+ export interface StandardSchemaV1<Input = unknown, Output = Input> {
3
+ readonly '~standard': StandardSchemaV1.Props<Input, Output>;
4
+ }
5
+ export declare namespace StandardSchemaV1 {
6
+ interface Props<Input = unknown, Output = Input> {
7
+ readonly version: 1;
8
+ readonly vendor: string;
9
+ readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
10
+ readonly types?: Types<Input, Output> | undefined;
11
+ }
12
+ type Result<Output> = SuccessResult<Output> | FailureResult;
13
+ interface SuccessResult<Output> {
14
+ readonly value: Output;
15
+ readonly issues?: undefined;
16
+ }
17
+ interface FailureResult {
18
+ readonly issues: ReadonlyArray<Issue>;
19
+ }
20
+ interface Issue {
21
+ readonly message: string;
22
+ readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
23
+ }
24
+ interface PathSegment {
25
+ readonly key: PropertyKey;
26
+ }
27
+ interface Types<Input = unknown, Output = Input> {
28
+ readonly input: Input;
29
+ readonly output: Output;
30
+ }
31
+ type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
32
+ }
33
+ export declare function isSchema(value: unknown): value is StandardSchemaV1;
34
+ /** The value a schema gives back, or the issues it found, spelled as one line. */
35
+ export declare function check<T>(schema: StandardSchemaV1<unknown, T>, value: unknown): Promise<{
36
+ value: T;
37
+ } | {
38
+ issues: string;
39
+ }>;
package/dist/schema.js ADDED
@@ -0,0 +1,21 @@
1
+ // Standard Schema, https://standardschema.dev: the interface zod, valibot and
2
+ // arktype each implement, copied here as the spec asks rather than depended on.
3
+ export function isSchema(value) {
4
+ return typeof value === 'object' && value !== null && '~standard' in value;
5
+ }
6
+ /** The value a schema gives back, or the issues it found, spelled as one line. */
7
+ export async function check(schema, value) {
8
+ const result = await schema['~standard'].validate(value);
9
+ if (result.issues === undefined) {
10
+ return { value: result.value };
11
+ }
12
+ const issues = result.issues
13
+ .map(issue => {
14
+ const path = issue.path
15
+ ?.map(segment => String(typeof segment === 'object' ? segment.key : segment))
16
+ .join('.');
17
+ return path === undefined || path === '' ? issue.message : `${path}: ${issue.message}`;
18
+ })
19
+ .join('; ');
20
+ return { issues };
21
+ }
@@ -0,0 +1,120 @@
1
+ import { ClosedError, type TinystoreError } from './errors.ts';
2
+ import type { Read } from './wire/codec.ts';
3
+ import { Welcome } from './wire/messages.ts';
4
+ export declare const protocol = 1;
5
+ /** What this client lets the server send on a stream before it grants more: a body at least. */
6
+ export declare const downloadWindow: number;
7
+ export type Agreed = Required<Omit<Read<typeof Welcome.fields>, 'proof'>>;
8
+ export interface SessionOptions {
9
+ /** a name and version, for the server's logs */
10
+ client: string;
11
+ /** a remote connection's token */
12
+ token?: string | undefined;
13
+ /** SERVE's secret, whose proof a local server must give before any call */
14
+ secret?: Uint8Array | undefined;
15
+ /** sixteen random bytes the proof answers; given with the secret */
16
+ challenge?: Uint8Array | undefined;
17
+ }
18
+ /**
19
+ * The connection was lost with a stream on it. Sent says whether its REQUEST
20
+ * had left: one that had not may go on another connection whatever it was,
21
+ * and one that had is a read to send again or a write whose outcome is
22
+ * unknown.
23
+ */
24
+ export declare class LostError extends ClosedError {
25
+ readonly sent: boolean;
26
+ constructor(message: string, sent: boolean);
27
+ }
28
+ /** A frame of a stream's answer: the RESPONSE, a DATA, or the error that ends it. */
29
+ export interface Event {
30
+ kind: 'response' | 'data';
31
+ body: Uint8Array;
32
+ end: boolean;
33
+ }
34
+ /**
35
+ * One stream: a client's REQUEST from its frame to the server's final frame,
36
+ * the one span in which its number is in use.
37
+ */
38
+ export declare class Stream {
39
+ #private;
40
+ readonly id: number;
41
+ readonly method: number;
42
+ /** the REQUEST has left, so the server may have acted on it */
43
+ sent: boolean;
44
+ /** the server's final frame came, or the connection ended */
45
+ finished: boolean;
46
+ constructor(session: Session, id: number, method: number, uploadCredit: number);
47
+ /** The next frame of the answer, or its error. */
48
+ next(): Promise<Event>;
49
+ /**
50
+ * Sends a body of an upload as DATA once the stream's credit lets it go;
51
+ * end says it is the last. Only an empty body ending the upload may be
52
+ * empty.
53
+ */
54
+ send(body: Uint8Array, end: boolean): Promise<void>;
55
+ /**
56
+ * Gives back what a DATA the server sent took of the stream's credit, once
57
+ * the caller has done with it; a grant goes once half the window has.
58
+ */
59
+ consumed(n: number): void;
60
+ /**
61
+ * Asks the server to stop. A stream whose REQUEST has not left never
62
+ * leaves; one that has keeps its number until the server's final frame,
63
+ * which is dropped.
64
+ */
65
+ cancel(): void;
66
+ get cancelled(): boolean;
67
+ deliver(event: Event): void;
68
+ /** Ends what waits on the stream with err; events already arrived are read first. */
69
+ fail(err: Error): void;
70
+ grant(n: number): void;
71
+ finish(): void;
72
+ /** Cancels the stream when the signal aborts, until the stream finishes. */
73
+ watchSignal(signal: AbortSignal): void;
74
+ }
75
+ /**
76
+ * The protocol of one connection. It writes through send, which the
77
+ * transport takes whole, and reads what receive is given, frames split
78
+ * anywhere.
79
+ */
80
+ export declare class Session {
81
+ #private;
82
+ /** resolves with what the WELCOME agreed, or rejects with why there is none */
83
+ readonly welcomed: Promise<Agreed>;
84
+ constructor(send: (bytes: Uint8Array) => void, options: SessionOptions);
85
+ get agreed(): Agreed | undefined;
86
+ /** The server said GOAWAY: no stream opens here any more. */
87
+ get goingAway(): boolean;
88
+ /** Why the connection ended, once it has. */
89
+ get ended(): Error | undefined;
90
+ /** Streams in use, their final frames not yet come. */
91
+ get streams(): number;
92
+ onEnd(listener: (err: Error) => void): void;
93
+ /**
94
+ * Opens a stream with its REQUEST. End says the REQUEST is the client's
95
+ * whole side; an upload's DATA follows through the stream otherwise. It
96
+ * waits while the streams in flight are all in use.
97
+ */
98
+ open(method: number, body: Uint8Array, end: boolean): Promise<Stream>;
99
+ /** A call: one REQUEST, and the RESPONSE that answers it. */
100
+ call(method: number, body: Uint8Array, signal?: AbortSignal): Promise<Uint8Array>;
101
+ enqueue(stream: Stream, bytes: Uint8Array, counted: number): void;
102
+ /** Writes a frame that does not wait for credit: a CREDIT, a CANCEL, a PONG. */
103
+ post(bytes: Uint8Array): void;
104
+ cancel(stream: Stream): void;
105
+ /** Takes bytes the transport read: any part of a frame, or several. */
106
+ receive(chunk: Uint8Array): void;
107
+ /** A frame broke the protocol: the connection ends, and whoever runs it closes it. */
108
+ fault(err: Error): void;
109
+ /**
110
+ * Ends the session: the transport closed, or a frame broke the protocol.
111
+ * Every stream still open learns whether its REQUEST had left.
112
+ */
113
+ end(err: Error): void;
114
+ }
115
+ /** Cancels a stream when a signal aborts; returns what stops watching. */
116
+ export declare function watch(signal: AbortSignal | undefined, stream: Stream): () => void;
117
+ /** The error a final frame with ERROR carries. */
118
+ export declare function failureOf(body: Uint8Array): TinystoreError;
119
+ /** A WELCOME's proof is the HMAC-SHA256 of the challenge keyed with SERVE's secret. */
120
+ export declare function proves(secret: Uint8Array, challenge: Uint8Array, proof: Uint8Array | undefined): boolean;