@tinyshed/tinystore 0.1.0-rc.1 → 0.1.0-rc.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +73 -221
- package/dist/logger.js +10 -2
- package/dist/sql.js +1 -1
- package/dist/store.d.ts +3 -1
- package/dist/store.js +23 -1
- package/package.json +7 -7
- package/src/logger.ts +12 -2
- package/src/sql.ts +1 -1
- package/src/store.ts +29 -1
package/README.md
CHANGED
|
@@ -1,262 +1,114 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
This is the page npm shows. The headline, the sample and the engines are the
|
|
3
|
+
landing page's: task readme writes them between the landing: markers from
|
|
4
|
+
web/landing.md. Every link is absolute, because npm cannot follow a relative
|
|
5
|
+
one. Every call, by engine, is in docs/reference/bun.md.
|
|
6
|
+
-->
|
|
7
|
+
|
|
1
8
|
# TinyStore for Bun and Node
|
|
2
9
|
|
|
3
|
-
|
|
4
|
-
sidecar the SDK starts. A Go program embeds the same engines;
|
|
5
|
-
[the guides](../../docs/README.md) show the three languages side by side.
|
|
10
|
+
<!-- landing:headline -->
|
|
6
11
|
|
|
7
|
-
|
|
8
|
-
bun add @tinyshed/tinystore
|
|
9
|
-
```
|
|
12
|
+
**A small storage runtime for applications.** SQL, key-value state, durable jobs, files, metrics and logs in one directory, with one lifecycle, one memory budget and one backup.
|
|
10
13
|
|
|
11
|
-
|
|
12
|
-
`tinystore` binary. `TINYSTORE_BIN`, `open`'s `binary` or `PATH` name another.
|
|
13
|
-
Bun 1.4 or later, or Node 22 or later, with one API: Bun runs the package's
|
|
14
|
-
TypeScript, and Node the JavaScript it carries.
|
|
14
|
+
<!-- /landing:headline -->
|
|
15
15
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
checks that source in their place with `"customConditions": ["bun"]` and
|
|
19
|
-
`"allowImportingTsExtensions": true`.
|
|
16
|
+
> **Release candidates first.** Until `v0.1.0`, the API may still change, and
|
|
17
|
+
> a file written by one release may not open in the next.
|
|
20
18
|
|
|
21
|
-
The
|
|
22
|
-
|
|
23
|
-
|
|
19
|
+
The SDK starts a small `tinystore` server next to your program, called the
|
|
20
|
+
sidecar, and talks to it over a local connection. The server binary comes with the
|
|
21
|
+
package, so there is nothing else to install. Go programs embed the same
|
|
22
|
+
engines, and every client of one directory sees the same data.
|
|
24
23
|
|
|
25
|
-
|
|
24
|
+
<!-- landing:sample -->
|
|
26
25
|
|
|
27
26
|
```ts
|
|
28
|
-
import {
|
|
29
|
-
|
|
30
|
-
await using store = await open('./data') // the directory's sidecar, started when none runs
|
|
31
|
-
await using alone = await open(dir, { private: true }) // a child of this process, for tests and scripts
|
|
32
|
-
await using remote = await connect('tls://db.internal:7070', { token })
|
|
33
|
-
|
|
34
|
-
await using test = await open(dir, { private: true, clock: new Date('2026-10-03T09:00:00Z') })
|
|
35
|
-
await test.clock.advance('1h') // keys expire and jobs come due without a wait
|
|
36
|
-
|
|
37
|
-
await store.backup('backup.zip') // every engine in one checked zip; tinystore restore takes it back
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
`open` returns once the server has answered, so a directory that cannot be
|
|
41
|
-
served fails there. Closing hands over the loggers' lines and the instruments'
|
|
42
|
-
last values; a sidecar leaves once its last connection has been idle 30 s.
|
|
27
|
+
import { open } from '@tinyshed/tinystore'
|
|
43
28
|
|
|
44
|
-
|
|
29
|
+
await using store = await open('./data')
|
|
45
30
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
await sessions.of(user.id).set(token, session)
|
|
49
|
-
const found = await sessions.of(user.id).get(token) // undefined when absent or expired
|
|
50
|
-
const { created, entry } = await sessions.of(user.id).setEntryIfAbsent(token, session) // this one, or the one there
|
|
51
|
-
|
|
52
|
-
const views = store.kv.counters('views')
|
|
53
|
-
await views.add('/home')
|
|
54
|
-
|
|
55
|
-
const page = await sessions.scan({ limit: 100 }) // { items, next }; next goes back as after
|
|
56
|
-
for await (const entry of sessions.all()) { … }
|
|
57
|
-
|
|
58
|
-
const userId = await store.kv.tx(async tx => { // reads, decides, writes; runs again if a key it read changed
|
|
59
|
-
const userId = await codes.withTx(tx).take(digest(code))
|
|
60
|
-
if (userId === undefined) throw new InvalidCodeError()
|
|
61
|
-
sessions.withTx(tx).of(userId).set(digest(token), session)
|
|
62
|
-
return userId
|
|
31
|
+
const db = await store.sql('app', {
|
|
32
|
+
migrations: { '0001_users.sql': 'create table users (id integer primary key, name text)' },
|
|
63
33
|
})
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
A bucket's type is given once, where it opens: JSON of `T`, a kind
|
|
67
|
-
(`'string'`, `'bytes'`, `'bigint'`, …) or a Standard Schema such as zod's,
|
|
68
|
-
which checks every read. `setIfAbsent` and `setEntryIfAbsent` write only
|
|
69
|
-
where no live key is, in one write: two processes making the same key, a
|
|
70
|
-
day's salt or a claim, keep one, where a `get` and then a `set` keep both.
|
|
71
|
-
|
|
72
|
-
```ts
|
|
73
|
-
import file from './config.yaml'
|
|
34
|
+
await db.exec`insert into users (id, name) values (${42}, ${'Ada'})`
|
|
74
35
|
|
|
75
|
-
const
|
|
76
|
-
|
|
77
|
-
await cfg.update({ port: 4000 }) // kept: 4000 after a restart too, at once in every process
|
|
78
|
-
await cfg.reset('port') // back to .env's 3000
|
|
79
|
-
cfg.watch(c => server.setPort(c.port))
|
|
36
|
+
const sessions = store.kv.bucket<string>('sessions', { sliding: '30d' })
|
|
37
|
+
await sessions.of('42').set('token', 'abc123')
|
|
80
38
|
|
|
81
|
-
const
|
|
82
|
-
|
|
39
|
+
const emails = store.jobs.queue<{ to: string }>('emails')
|
|
40
|
+
await emails.enqueue({ to: 'ada@example.com' })
|
|
83
41
|
|
|
84
|
-
const
|
|
85
|
-
|
|
86
|
-
```
|
|
42
|
+
const files = store.blobs.bucket('files')
|
|
43
|
+
await files.put('avatars/42.png', Bun.file('avatar.png'))
|
|
87
44
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
field, `dbUrl` as `DB_URL`, after `prefix` when given. A number, `true`, a
|
|
91
|
-
list `a.com,b.com` or JSON read as the default's kind, and one that does not
|
|
92
|
-
is `InvalidError` at open, naming it. `env: { dbUrl: 'DATABASE_URL' }` names a
|
|
93
|
-
variable itself; `secret` fields are never kept; `schema` checks each change.
|
|
94
|
-
A quota's windows count a use together or not at all, each from a key's first
|
|
95
|
-
use; `get` reads them without using any, `refund` gives uses back.
|
|
45
|
+
const log = store.records.logger('api')
|
|
46
|
+
log.event('user.created', { userId: 42 })
|
|
96
47
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
const receipt = await charges.run(requestId, () => pay.charge(order, requestId))
|
|
48
|
+
const signups = store.metrics.counter('signups_total')
|
|
49
|
+
signups.inc()
|
|
100
50
|
```
|
|
101
51
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
gets the same answer, and a throw keeps nothing, so the next call runs again.
|
|
105
|
-
The function runs once a key while its call lives; an effect outside the
|
|
106
|
-
store, a charge, carries the key too.
|
|
107
|
-
|
|
108
|
-
## jobs
|
|
109
|
-
|
|
110
|
-
```ts
|
|
111
|
-
const reminders = store.jobs.queue<{ note: number }>('reminders')
|
|
112
|
-
await reminders.enqueue({ note: 1 }, { after: '1h', key: 'note/1' })
|
|
113
|
-
|
|
114
|
-
await reminders.work(async job => {
|
|
115
|
-
await remind(job.value.note, { signal: job.signal })
|
|
116
|
-
}, { workers: 4, signal })
|
|
52
|
+
```sh
|
|
53
|
+
bun add @tinyshed/tinystore
|
|
117
54
|
```
|
|
118
55
|
|
|
119
|
-
|
|
120
|
-
each time; `job.retry`, `job.fail` and `job.snooze` say otherwise. `work` runs
|
|
121
|
-
until its signal aborts; the jobs in hand finish first.
|
|
56
|
+
<!-- /landing:sample -->
|
|
122
57
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
for await (const s of videos.watch(video.id)) send(s.state, s.ahead, s.progress) // waiting 3 … running 0.4 … done
|
|
127
|
-
|
|
128
|
-
await videos.work(async job => {
|
|
129
|
-
await transcode(job.value, { signal: job.signal, onProgress: p => job.progress(p) })
|
|
130
|
-
})
|
|
131
|
-
```
|
|
58
|
+
It runs on Bun 1.4 or later and Node 22 or later, with the same API. Bun runs
|
|
59
|
+
the package's TypeScript, and Node runs the JavaScript that the package
|
|
60
|
+
contains. With npm, pnpm or Yarn, install it as `npm install @tinyshed/tinystore`.
|
|
132
61
|
|
|
133
|
-
|
|
134
|
-
`running`, with the `progress` its handler last reported, `failed`, or `done`
|
|
135
|
-
while `keepDone` keeps its key; `watch` yields it again at each change until
|
|
136
|
-
it ends, `cancelled` included, and `ran` and `took` say when the last run a
|
|
137
|
-
handler finished began and how many milliseconds it took: a schedule's last
|
|
138
|
-
run beside its next, `at`. `job.progress` takes any JSON within 4 KiB and
|
|
139
|
-
sends the latest at most ten times a second. `cancel` takes a running job too:
|
|
140
|
-
its `job.signal` aborts with a `CancelledError`, and what the handler returns
|
|
141
|
-
settles nothing. `maxRunning` bounds the jobs running at once across every
|
|
142
|
-
worker of the store.
|
|
62
|
+
## Engines
|
|
143
63
|
|
|
144
|
-
|
|
145
|
-
does not run it again: `const hits = await job.step('search', () => search(q))`.
|
|
64
|
+
<!-- landing:engines -->
|
|
146
65
|
|
|
147
|
-
|
|
66
|
+
| | | |
|
|
67
|
+
|---|---|---|
|
|
68
|
+
| [SQL](https://github.com/tinyshed/tinystore/blob/main/docs/sql/README.md) | Relational state | The application's own SQL databases: tables from structs, checked migrations. |
|
|
69
|
+
| [KV](https://github.com/tinyshed/tinystore/blob/main/docs/kv/README.md) | Application state | Current state: typed buckets, counters, expiry, versions. |
|
|
70
|
+
| [Jobs](https://github.com/tinyshed/tinystore/blob/main/docs/jobs/README.md) | Durable background work | Work that runs at its time: retries, leases, repeats. |
|
|
71
|
+
| [Blobs](https://github.com/tinyshed/tinystore/blob/main/docs/blobs/README.md) | Files and objects | Files by path, checked when read whole. |
|
|
72
|
+
| [Records](https://github.com/tinyshed/tinystore/blob/main/docs/records/README.md) | Logs and events | Read by time, level and keys. |
|
|
73
|
+
| [Metrics](https://github.com/tinyshed/tinystore/blob/main/docs/metrics/README.md) | Time series | Samples kept bit for bit, answered exactly. |
|
|
148
74
|
|
|
149
|
-
|
|
150
|
-
const files = store.blobs.bucket('files')
|
|
151
|
-
await files.put('avatars/42.png', Bun.file('avatar.png'))
|
|
152
|
-
const avatar = await files.get('avatars/42.png') // undefined when absent
|
|
153
|
-
const bytes = await avatar?.bytes() // a whole read checks every byte
|
|
154
|
-
```
|
|
75
|
+
<!-- /landing:engines -->
|
|
155
76
|
|
|
156
|
-
##
|
|
77
|
+
## Three ways to connect
|
|
157
78
|
|
|
158
79
|
```ts
|
|
159
|
-
|
|
160
|
-
await app.exec`insert into notes (body) values (${body})`
|
|
161
|
-
const notes = await app.all<Note>`select id, body from notes where author = ${author}`
|
|
162
|
-
await app.batch(tx => { // one transaction, all or none
|
|
163
|
-
tx.exec`update notes set body = ${body} where id = ${id}`
|
|
164
|
-
tx.exec`insert into edits (note) values (${id})`
|
|
165
|
-
})
|
|
166
|
-
const [page, total] = await app.view(tx => [tx.all`select * from notes limit 20`, tx.scalar`select count(*) from notes`])
|
|
80
|
+
import { connect, open } from '@tinyshed/tinystore'
|
|
167
81
|
|
|
168
|
-
|
|
169
|
-
await
|
|
170
|
-
|
|
171
|
-
index.withTx(tx).enqueue({ id }) // commits with the update, or not at all
|
|
172
|
-
})
|
|
82
|
+
await using store = await open('./data') // the directory's sidecar, shared with other processes
|
|
83
|
+
await using alone = await open('./data', { private: true }) // a server for this process alone, for tests and scripts
|
|
84
|
+
await using remote = await connect('tls://db.internal:7070', { token })
|
|
173
85
|
```
|
|
174
86
|
|
|
175
|
-
|
|
176
|
-
|
|
87
|
+
[The sidecar](https://github.com/tinyshed/tinystore/blob/main/docs/running/sidecar.md)
|
|
88
|
+
and [A remote server](https://github.com/tinyshed/tinystore/blob/main/docs/running/server.md)
|
|
89
|
+
explain each one.
|
|
177
90
|
|
|
178
|
-
##
|
|
179
|
-
|
|
180
|
-
```ts
|
|
181
|
-
const log = store.records.logger('api', { redact: ['password'] }) // never waits for the server
|
|
182
|
-
log.with({ requestId }).warn('slow request', { ms: 1200 })
|
|
183
|
-
log.event('user.created', { userId: 42 })
|
|
184
|
-
await withTrace({ traceId, spanId }, async () => log.info('charged')) // the record carries the trace
|
|
91
|
+
## The command line
|
|
185
92
|
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
const more = await store.records.scan({ since: '1h', minLevel: 'warn', limit: 100, after: page.next })
|
|
189
|
-
for await (const record of store.records.all({ since: '24h', traceId })) { … }
|
|
190
|
-
const { ms } = fields(page.items[0].attrs) // a record's [key, json] pairs, as JSON.parse reads them
|
|
93
|
+
The package also installs the `tinystore` command. It shows what a store
|
|
94
|
+
contains and follows its logs while your program runs:
|
|
191
95
|
|
|
192
|
-
|
|
193
|
-
|
|
96
|
+
```sh
|
|
97
|
+
bunx @tinyshed/tinystore status ./data # each engine's size, and who serves the directory
|
|
98
|
+
bunx @tinyshed/tinystore logs ./data -f # the application's logs, as they arrive
|
|
99
|
+
claude mcp add tinystore -- bunx @tinyshed/tinystore mcp ./data # read-only access for an AI agent
|
|
194
100
|
```
|
|
195
101
|
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
stderr. A logger is for lines a burst may cost: what must all be kept goes
|
|
199
|
-
through `records.append`, which answers once it is, and a larger `buffer`
|
|
200
|
-
holds a longer burst.
|
|
201
|
-
|
|
202
|
-
Each line also goes to stderr as it is logged: pretty on a terminal, one JSON
|
|
203
|
-
object a line otherwise, the bytes Go's and Python's loggers write.
|
|
204
|
-
`console: 'pretty' | 'json' | 'off'` and `stdout: true` choose, and a logger
|
|
205
|
-
of events, a view a request, takes `'off'` or fills the program's log; `redact`
|
|
206
|
-
hides the values of fields of those names, at any depth, the case ignored, in
|
|
207
|
-
the store and on the console. A program that wants the logger and not the
|
|
208
|
-
records takes one without a store, and passes it, or a child, to what needs
|
|
209
|
-
it:
|
|
210
|
-
|
|
211
|
-
```ts
|
|
212
|
-
import { logger } from '@tinyshed/tinystore'
|
|
102
|
+
See [The command line](https://github.com/tinyshed/tinystore/blob/main/docs/running/cli.md)
|
|
103
|
+
for every command.
|
|
213
104
|
|
|
214
|
-
|
|
215
|
-
const db = log.with({ module: 'db' })
|
|
216
|
-
```
|
|
105
|
+
## Documentation
|
|
217
106
|
|
|
218
|
-
|
|
107
|
+
- [Getting started](https://github.com/tinyshed/tinystore/blob/main/docs/getting-started.md): install it and write a first program
|
|
108
|
+
- [A tour](https://github.com/tinyshed/tinystore/blob/main/docs/tour.md): every engine on one page
|
|
109
|
+
- [The guides](https://github.com/tinyshed/tinystore/blob/main/docs/README.md): a page per feature, each example in Bun, Python and Go
|
|
110
|
+
- [Bun and Node API](https://github.com/tinyshed/tinystore/blob/main/docs/reference/bun.md): every call, by engine
|
|
219
111
|
|
|
220
|
-
|
|
221
|
-
store.metrics.counter('http_requests_total').with({ route: '/users' }).inc()
|
|
222
|
-
store.metrics.gauge('queue_depth').set(12)
|
|
223
|
-
const latency = store.metrics.timer('http_request_ms')
|
|
224
|
-
const user = await latency.with({ route: '/users' }).measure(() => users.get(id))
|
|
225
|
-
|
|
226
|
-
await store.metrics.ingest({ name: 'cpu', kind: 'gauge', labels: { host: 'web-1' }, samples: [[new Date(), 0.42]] })
|
|
227
|
-
const series = await store.metrics.read({ name: 'cpu', match: { host: 'web-1' }, since: '1h' }) // columns: times, values
|
|
228
|
-
const failing = await store.metrics.read({ name: 'http_requests_total', since: '1h', where: { status: oneOf('500', '502') } })
|
|
229
|
-
const buckets = await store.metrics.aggregate({ name: 'http_requests_total', since: '24h', width: '1h', op: 'increase' })
|
|
230
|
-
const routes = await store.metrics.aggregate({ name: 'http_requests_total', since: '24h', width: '1h', op: 'rate', by: ['route'] })
|
|
231
|
-
```
|
|
112
|
+
## License
|
|
232
113
|
|
|
233
|
-
|
|
234
|
-
`values` a `Float64Array`, as `ingest` takes them too beside `[time, value]`
|
|
235
|
-
pairs. A sample comes back bit for bit, `-0` and a NaN's payload included; a
|
|
236
|
-
range is `since`, or `from` and `to` in unix milliseconds.
|
|
237
|
-
`metrics.explain(range)` says what a read or an aggregate would spend of its
|
|
238
|
-
limits before it runs.
|
|
239
|
-
|
|
240
|
-
A timer's `measure(fn)` answers what `fn` answered and throws what it threw,
|
|
241
|
-
recording the time either way; `record(ms)` adds a duration of its own. Every
|
|
242
|
-
flush writes `http_request_ms_count` and `http_request_ms_sum`, counters, and
|
|
243
|
-
the longest since the flush before, `http_request_ms_max`, so that a range's
|
|
244
|
-
mean is the increase of its sum over the increase of its count. A series the
|
|
245
|
-
store refuses, a label it cannot keep, is left out from then on and said
|
|
246
|
-
once, and the other instruments go on being written.
|
|
247
|
-
|
|
248
|
-
## Errors and cancellation
|
|
249
|
-
|
|
250
|
-
Every error is its code's class, a `TinystoreError`: `InvalidError`,
|
|
251
|
-
`ConflictError`, `LimitError`, `TooOldError` and the rest, each carrying what it
|
|
252
|
-
names; a `LimitError` names the bound, what the call wanted and the bound.
|
|
253
|
-
Every call inside `withSignal(signal, fn)` ends when the signal aborts, one
|
|
254
|
-
`CANCEL` on the wire; `work`, `put` and `get` of blobs also take a signal of
|
|
255
|
-
their own. `await store.status()` says what the server is: its version, its
|
|
256
|
-
protocol, its engines.
|
|
257
|
-
|
|
258
|
-
What fails where no call waits is said on stderr, as a logger of stream
|
|
259
|
-
`tinystore` writes a line: an instrument's flush or a logger's write that
|
|
260
|
-
failed, and its recovery; a gauge's function that threw; a refused
|
|
261
|
-
instrument; the lines a full logger dropped. A failure repeated is said again
|
|
262
|
-
ten minutes on, or when it changes, as Go's store logs its own.
|
|
114
|
+
Apache-2.0.
|
package/dist/logger.js
CHANGED
|
@@ -54,18 +54,26 @@ export const sayOwn = (level, message, fields) => {
|
|
|
54
54
|
own ??= logger('tinystore');
|
|
55
55
|
own[level](message, fields);
|
|
56
56
|
};
|
|
57
|
+
function forceColor() {
|
|
58
|
+
const force = process.env.FORCE_COLOR;
|
|
59
|
+
return force !== undefined && force !== '' && force !== '0';
|
|
60
|
+
}
|
|
57
61
|
/** How a logger prints its lines, or undefined when it prints none. */
|
|
58
62
|
function printer(options, out) {
|
|
59
63
|
if (options.console === 'off') {
|
|
60
64
|
return undefined;
|
|
61
65
|
}
|
|
62
66
|
const stream = out ?? (options.stdout === true ? process.stdout : process.stderr);
|
|
67
|
+
// FORCE_COLOR other than 0 says a person reads a pipe, as an IDE's run console is one
|
|
68
|
+
const forced = out === undefined && forceColor();
|
|
63
69
|
const terminal = stream.isTTY === true;
|
|
64
|
-
const pretty = options.console === 'pretty' || (options.console === undefined && terminal);
|
|
70
|
+
const pretty = options.console === 'pretty' || (options.console === undefined && (terminal || forced));
|
|
65
71
|
if (!pretty) {
|
|
66
72
|
return line => void stream.write(jsonLine(line));
|
|
67
73
|
}
|
|
68
|
-
const color = terminal && out === undefined &&
|
|
74
|
+
const color = (forced || (terminal && out === undefined)) &&
|
|
75
|
+
!process.env.NO_COLOR &&
|
|
76
|
+
process.env.TERM !== 'dumb';
|
|
69
77
|
return line => void stream.write(prettyLine(line, color, out?.utc === true));
|
|
70
78
|
}
|
|
71
79
|
/**
|
package/dist/sql.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// The application's own SQLite databases, sql/<name>.db, as Go's sqldb keeps
|
|
2
2
|
// them: the application writes every query, the server owns the file, its
|
|
3
3
|
// connections and its migrations, which the first open applies and every
|
|
4
|
-
// later one checks.
|
|
4
|
+
// later one checks. An open without migrations takes the file as it is.
|
|
5
5
|
import { readdir, readFile } from 'node:fs/promises';
|
|
6
6
|
import { join } from 'node:path';
|
|
7
7
|
import { InvalidError } from './errors.js';
|
package/dist/store.d.ts
CHANGED
|
@@ -68,7 +68,9 @@ export declare class Store implements AsyncDisposable {
|
|
|
68
68
|
/**
|
|
69
69
|
* Opens a database of the application's own, sql/<name>.db. The first open
|
|
70
70
|
* in the server, on an admin connection, applies its migrations; every
|
|
71
|
-
* later one checks them against what the file applied.
|
|
71
|
+
* later one checks them against what the file applied. Without migrations
|
|
72
|
+
* it opens the file as it is, an empty one if there is none, and checks
|
|
73
|
+
* nothing.
|
|
72
74
|
*/
|
|
73
75
|
sql(name: string, options?: SqlOptions): Promise<Database>;
|
|
74
76
|
/**
|
package/dist/store.js
CHANGED
|
@@ -53,7 +53,9 @@ export class Store {
|
|
|
53
53
|
/**
|
|
54
54
|
* Opens a database of the application's own, sql/<name>.db. The first open
|
|
55
55
|
* in the server, on an admin connection, applies its migrations; every
|
|
56
|
-
* later one checks them against what the file applied.
|
|
56
|
+
* later one checks them against what the file applied. Without migrations
|
|
57
|
+
* it opens the file as it is, an empty one if there is none, and checks
|
|
58
|
+
* nothing.
|
|
57
59
|
*/
|
|
58
60
|
sql(name, options) {
|
|
59
61
|
return openDatabase(this.#link, name, options);
|
|
@@ -121,6 +123,7 @@ export async function open(dir, options = {}) {
|
|
|
121
123
|
return openWith(runtime, dir, options);
|
|
122
124
|
}
|
|
123
125
|
export async function openWith(runtime, dir, options = {}) {
|
|
126
|
+
checkDirectory(dir);
|
|
124
127
|
const binary = () => findBinary(runtime, options.binary);
|
|
125
128
|
const idle = options.idle === undefined ? undefined : ms(options.idle);
|
|
126
129
|
if (options.clock !== undefined && options.private !== true) {
|
|
@@ -143,6 +146,25 @@ export async function connect(url, options) {
|
|
|
143
146
|
await link.connection();
|
|
144
147
|
return new Store(link);
|
|
145
148
|
}
|
|
149
|
+
// two letters or more before a colon: an address, never a Windows drive
|
|
150
|
+
const address = /^([a-z][a-z0-9+.-]+):/i;
|
|
151
|
+
/**
|
|
152
|
+
* Refuses an address where a directory belongs: open('tcp://…') would make a
|
|
153
|
+
* folder of that name and start a server in it, rather than reach the one meant.
|
|
154
|
+
*
|
|
155
|
+
* open('tcp://db.internal:7070') → use connect
|
|
156
|
+
* open('pipe:tinystore-d761f24b7e59') → open the directory it serves
|
|
157
|
+
* open('C:/data') → a directory
|
|
158
|
+
*/
|
|
159
|
+
function checkDirectory(dir) {
|
|
160
|
+
const scheme = address.exec(dir)?.[1]?.toLowerCase();
|
|
161
|
+
if (scheme === 'tcp' || scheme === 'tls') {
|
|
162
|
+
throw new InvalidError(`open takes a store's directory, and ${dir} is a server's address: connect('${dir}', { token }) reaches it`);
|
|
163
|
+
}
|
|
164
|
+
if (scheme !== undefined) {
|
|
165
|
+
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`);
|
|
166
|
+
}
|
|
167
|
+
}
|
|
146
168
|
function findBinary(runtime, given) {
|
|
147
169
|
const found = given ?? process.env.TINYSTORE_BIN ?? runtime.packagedBinary() ?? runtime.which('tinystore');
|
|
148
170
|
if (found === undefined || found === '') {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tinyshed/tinystore",
|
|
3
|
-
"version": "0.1.0-rc.
|
|
3
|
+
"version": "0.1.0-rc.3",
|
|
4
4
|
"description": "TinyStore for Bun and Node: kv, jobs, blobs, SQL, records and metrics in one directory, served by a sidecar",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
@@ -30,11 +30,11 @@
|
|
|
30
30
|
"README.md"
|
|
31
31
|
],
|
|
32
32
|
"optionalDependencies": {
|
|
33
|
-
"@tinyshed/tinystore-darwin-arm64": "0.1.0-rc.
|
|
34
|
-
"@tinyshed/tinystore-darwin-x64": "0.1.0-rc.
|
|
35
|
-
"@tinyshed/tinystore-linux-arm64": "0.1.0-rc.
|
|
36
|
-
"@tinyshed/tinystore-linux-x64": "0.1.0-rc.
|
|
37
|
-
"@tinyshed/tinystore-win32-arm64": "0.1.0-rc.
|
|
38
|
-
"@tinyshed/tinystore-win32-x64": "0.1.0-rc.
|
|
33
|
+
"@tinyshed/tinystore-darwin-arm64": "0.1.0-rc.3",
|
|
34
|
+
"@tinyshed/tinystore-darwin-x64": "0.1.0-rc.3",
|
|
35
|
+
"@tinyshed/tinystore-linux-arm64": "0.1.0-rc.3",
|
|
36
|
+
"@tinyshed/tinystore-linux-x64": "0.1.0-rc.3",
|
|
37
|
+
"@tinyshed/tinystore-win32-arm64": "0.1.0-rc.3",
|
|
38
|
+
"@tinyshed/tinystore-win32-x64": "0.1.0-rc.3"
|
|
39
39
|
}
|
|
40
40
|
}
|
package/src/logger.ts
CHANGED
|
@@ -112,19 +112,29 @@ export const sayOwn: Say = (level, message, fields) => {
|
|
|
112
112
|
own[level](message, fields)
|
|
113
113
|
}
|
|
114
114
|
|
|
115
|
+
function forceColor(): boolean {
|
|
116
|
+
const force = process.env.FORCE_COLOR
|
|
117
|
+
return force !== undefined && force !== '' && force !== '0'
|
|
118
|
+
}
|
|
119
|
+
|
|
115
120
|
/** How a logger prints its lines, or undefined when it prints none. */
|
|
116
121
|
function printer(options: LoggerOptions, out?: ConsoleOut & { utc?: boolean }): Shared['print'] {
|
|
117
122
|
if (options.console === 'off') {
|
|
118
123
|
return undefined
|
|
119
124
|
}
|
|
120
125
|
const stream: ConsoleOut = out ?? (options.stdout === true ? process.stdout : process.stderr)
|
|
126
|
+
// FORCE_COLOR other than 0 says a person reads a pipe, as an IDE's run console is one
|
|
127
|
+
const forced = out === undefined && forceColor()
|
|
121
128
|
const terminal = stream.isTTY === true
|
|
122
|
-
const pretty =
|
|
129
|
+
const pretty =
|
|
130
|
+
options.console === 'pretty' || (options.console === undefined && (terminal || forced))
|
|
123
131
|
if (!pretty) {
|
|
124
132
|
return line => void stream.write(jsonLine(line))
|
|
125
133
|
}
|
|
126
134
|
const color =
|
|
127
|
-
terminal && out === undefined &&
|
|
135
|
+
(forced || (terminal && out === undefined)) &&
|
|
136
|
+
!process.env.NO_COLOR &&
|
|
137
|
+
process.env.TERM !== 'dumb'
|
|
128
138
|
return line => void stream.write(prettyLine(line, color, out?.utc === true))
|
|
129
139
|
}
|
|
130
140
|
|
package/src/sql.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// The application's own SQLite databases, sql/<name>.db, as Go's sqldb keeps
|
|
2
2
|
// them: the application writes every query, the server owns the file, its
|
|
3
3
|
// connections and its migrations, which the first open applies and every
|
|
4
|
-
// later one checks.
|
|
4
|
+
// later one checks. An open without migrations takes the file as it is.
|
|
5
5
|
|
|
6
6
|
import { readdir, readFile } from 'node:fs/promises'
|
|
7
7
|
import { join } from 'node:path'
|
package/src/store.ts
CHANGED
|
@@ -98,7 +98,9 @@ export class Store implements AsyncDisposable {
|
|
|
98
98
|
/**
|
|
99
99
|
* Opens a database of the application's own, sql/<name>.db. The first open
|
|
100
100
|
* in the server, on an admin connection, applies its migrations; every
|
|
101
|
-
* later one checks them against what the file applied.
|
|
101
|
+
* later one checks them against what the file applied. Without migrations
|
|
102
|
+
* it opens the file as it is, an empty one if there is none, and checks
|
|
103
|
+
* nothing.
|
|
102
104
|
*/
|
|
103
105
|
sql(name: string, options?: SqlOptions): Promise<Database> {
|
|
104
106
|
return openDatabase(this.#link, name, options)
|
|
@@ -178,6 +180,7 @@ export async function openWith(
|
|
|
178
180
|
dir: string,
|
|
179
181
|
options: OpenOptions = {},
|
|
180
182
|
): Promise<Store> {
|
|
183
|
+
checkDirectory(dir)
|
|
181
184
|
const binary = () => findBinary(runtime, options.binary)
|
|
182
185
|
const idle = options.idle === undefined ? undefined : ms(options.idle)
|
|
183
186
|
if (options.clock !== undefined && options.private !== true) {
|
|
@@ -206,6 +209,31 @@ export async function connect(url: string, options: ConnectOptions): Promise<Sto
|
|
|
206
209
|
return new Store(link)
|
|
207
210
|
}
|
|
208
211
|
|
|
212
|
+
// two letters or more before a colon: an address, never a Windows drive
|
|
213
|
+
const address = /^([a-z][a-z0-9+.-]+):/i
|
|
214
|
+
|
|
215
|
+
/**
|
|
216
|
+
* Refuses an address where a directory belongs: open('tcp://…') would make a
|
|
217
|
+
* folder of that name and start a server in it, rather than reach the one meant.
|
|
218
|
+
*
|
|
219
|
+
* open('tcp://db.internal:7070') → use connect
|
|
220
|
+
* open('pipe:tinystore-d761f24b7e59') → open the directory it serves
|
|
221
|
+
* open('C:/data') → a directory
|
|
222
|
+
*/
|
|
223
|
+
function checkDirectory(dir: string): void {
|
|
224
|
+
const scheme = address.exec(dir)?.[1]?.toLowerCase()
|
|
225
|
+
if (scheme === 'tcp' || scheme === 'tls') {
|
|
226
|
+
throw new InvalidError(
|
|
227
|
+
`open takes a store's directory, and ${dir} is a server's address: connect('${dir}', { token }) reaches it`,
|
|
228
|
+
)
|
|
229
|
+
}
|
|
230
|
+
if (scheme !== undefined) {
|
|
231
|
+
throw new InvalidError(
|
|
232
|
+
`open takes a store's directory, and ${dir} is an address: open the directory its server serves, and it is found through SERVE`,
|
|
233
|
+
)
|
|
234
|
+
}
|
|
235
|
+
}
|
|
236
|
+
|
|
209
237
|
function findBinary(runtime: Runtime, given: string | undefined): string {
|
|
210
238
|
const found =
|
|
211
239
|
given ?? process.env.TINYSTORE_BIN ?? runtime.packagedBinary() ?? runtime.which('tinystore')
|