@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 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
- kv, jobs, blobs, SQL, records and metrics in one directory, served by a
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
- ```sh
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
- The package for this platform, an optional dependency, carries the
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
- From a checkout, `bun add ../tinystore/sdk/js` installs the package as its
17
- source. The declarations `types` names are built by a release, so TypeScript
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 binary is the `tinystore` command too: `bunx @tinyshed/tinystore status ./data`,
22
- `bunx @tinyshed/tinystore logs ./data -f`, and for an AI agent
23
- `claude mcp add tinystore -- bunx @tinyshed/tinystore mcp ./data`.
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
- ## Open
24
+ <!-- landing:sample -->
26
25
 
27
26
  ```ts
28
- import { connect, open } from '@tinyshed/tinystore'
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
- ## kv
29
+ await using store = await open('./data')
45
30
 
46
- ```ts
47
- const sessions = store.kv.bucket<Session>('sessions', { sliding: '30d' })
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 cfg = await store.kv.config('app', { port: 8080, dbUrl: '', origins: ['localhost'] }, { file })
76
- cfg.value.port // PORT=3000 in .env makes it 3000
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 limit = store.kv.limiter('api', { rate: '100/s', burst: 20 })
82
- const { ok, retryAfter } = await limit.of(tenant).allow(userId)
39
+ const emails = store.jobs.queue<{ to: string }>('emails')
40
+ await emails.enqueue({ to: 'ada@example.com' })
83
41
 
84
- const ai = store.kv.quota('ai', { session: '100/5h', weekly: '300/7d' })
85
- const usage = await ai.allow(user.id) // one of each window, or none: usage.windows.weekly.left
86
- ```
42
+ const files = store.blobs.bucket('files')
43
+ await files.put('avatars/42.png', Bun.file('avatar.png'))
87
44
 
88
- A config is shaped and typed by its defaults: a file's values, then the
89
- environment, then what `update` kept go over them, a variable named by its
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
- ```ts
98
- const charges = store.kv.once<Receipt>('charges') // answers kept a day
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
- `run` returns the answer kept under a key, or runs the function and keeps
103
- its answer: a call of the key meanwhile, from any client, waits for it and
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
- A handler's return acknowledges its job and a throw retries it, waiting longer
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
- ```ts
124
- const videos = store.jobs.queue<Video>('videos', { maxRunning: 2 })
125
- await videos.enqueue(video, { key: video.id })
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
- `get` says where a job is: `waiting`, with how many jobs run `ahead` of it,
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
- A step of a job's run keeps its answer, so that the attempt after a failure
145
- does not run it again: `const hits = await job.step('search', () => search(q))`.
64
+ <!-- landing:engines -->
146
65
 
147
- ## blobs
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
- ```ts
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
- ## SQL
77
+ ## Three ways to connect
157
78
 
158
79
  ```ts
159
- const app = await store.sql('app', { migrations: './migrations' })
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
- const index = store.jobs.queue<{ id: number }>('index', { in: app }) // the queue lives in sql/app.db
169
- await app.batch(tx => {
170
- tx.exec`update notes set body = ${body} where id = ${id}`
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
- A value comes back as SQLite keeps it; a template's values are arguments,
176
- never SQL.
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
- ## records
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
- const page = await store.records.scan({ since: '1h', minLevel: 'warn', limit: 100 })
187
- const resets = await store.records.scan({ since: '1h', search: 'connection reset' }) // case ignored
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
- const worker = store.records.lines('worker') // another program's output, cut anywhere
193
- for await (const chunk of child.stdout) worker.write(chunk)
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
- A logger holds 1024 lines and hands them over every second or once half of
197
- them wait; what does not fit is dropped, counted in `log.dropped` and said on
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
- const log = logger('app', { redact: ['password'] }) // the console alone, nothing kept
215
- const db = log.with({ module: 'db' })
216
- ```
105
+ ## Documentation
217
106
 
218
- ## metrics
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
- ```ts
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
- A read answers each series as columns, `times` in unix milliseconds and
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 && !process.env.NO_COLOR && process.env.TERM !== 'dumb';
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.1",
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.1",
34
- "@tinyshed/tinystore-darwin-x64": "0.1.0-rc.1",
35
- "@tinyshed/tinystore-linux-arm64": "0.1.0-rc.1",
36
- "@tinyshed/tinystore-linux-x64": "0.1.0-rc.1",
37
- "@tinyshed/tinystore-win32-arm64": "0.1.0-rc.1",
38
- "@tinyshed/tinystore-win32-x64": "0.1.0-rc.1"
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 = options.console === 'pretty' || (options.console === undefined && terminal)
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 && !process.env.NO_COLOR && process.env.TERM !== 'dumb'
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')