@tinyshed/tinystore 0.1.0-rc.1 → 0.1.0-rc.2

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 (2) hide show
  1. package/README.md +72 -222
  2. package/package.json +7 -7
package/README.md CHANGED
@@ -1,262 +1,112 @@
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
63
- })
64
- ```
31
+ const db = await store.sql('app')
32
+ await db.exec`insert into users (id, name) values (${42}, ${'Ada'})`
65
33
 
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.
34
+ const sessions = store.kv.bucket<string>('sessions', { sliding: '30d' })
35
+ await sessions.of('42').set('token', 'abc123')
71
36
 
72
- ```ts
73
- import file from './config.yaml'
37
+ const emails = store.jobs.queue<{ to: string }>('emails')
38
+ await emails.enqueue({ to: 'ada@example.com' })
74
39
 
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))
40
+ const files = store.blobs.bucket('files')
41
+ await files.put('avatars/42.png', Bun.file('avatar.png'))
80
42
 
81
- const limit = store.kv.limiter('api', { rate: '100/s', burst: 20 })
82
- const { ok, retryAfter } = await limit.of(tenant).allow(userId)
43
+ const log = store.records.logger('api')
44
+ log.event('user.created', { userId: 42 })
83
45
 
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
46
+ const signups = store.metrics.counter('signups_total')
47
+ signups.inc()
86
48
  ```
87
49
 
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.
96
-
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))
50
+ ```sh
51
+ bun add @tinyshed/tinystore
100
52
  ```
101
53
 
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
54
+ <!-- /landing:sample -->
109
55
 
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 })
117
- ```
56
+ It runs on Bun 1.4 or later and Node 22 or later, with the same API. Bun runs
57
+ the package's TypeScript, and Node runs the JavaScript that the package
58
+ contains. With npm, pnpm or Yarn, install it as `npm install @tinyshed/tinystore`.
118
59
 
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.
60
+ ## Engines
122
61
 
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
- ```
62
+ <!-- landing:engines -->
132
63
 
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.
64
+ | | | |
65
+ |---|---|---|
66
+ | [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. |
67
+ | [KV](https://github.com/tinyshed/tinystore/blob/main/docs/kv/README.md) | Application state | Current state: typed buckets, counters, expiry, versions. |
68
+ | [Jobs](https://github.com/tinyshed/tinystore/blob/main/docs/jobs/README.md) | Durable background work | Work that runs at its time: retries, leases, repeats. |
69
+ | [Blobs](https://github.com/tinyshed/tinystore/blob/main/docs/blobs/README.md) | Files and objects | Files by path, checked when read whole. |
70
+ | [Records](https://github.com/tinyshed/tinystore/blob/main/docs/records/README.md) | Logs and events | Read by time, level and keys. |
71
+ | [Metrics](https://github.com/tinyshed/tinystore/blob/main/docs/metrics/README.md) | Time series | Samples kept bit for bit, answered exactly. |
143
72
 
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))`.
73
+ <!-- /landing:engines -->
146
74
 
147
- ## blobs
75
+ ## Three ways to connect
148
76
 
149
77
  ```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
- ```
155
-
156
- ## SQL
78
+ import { connect, open } from '@tinyshed/tinystore'
157
79
 
158
- ```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`])
167
-
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
- })
80
+ await using store = await open('./data') // the directory's sidecar, shared with other processes
81
+ await using alone = await open('./data', { private: true }) // a server for this process alone, for tests and scripts
82
+ await using remote = await connect('tls://db.internal:7070', { token })
173
83
  ```
174
84
 
175
- A value comes back as SQLite keeps it; a template's values are arguments,
176
- never SQL.
177
-
178
- ## records
85
+ [The sidecar](https://github.com/tinyshed/tinystore/blob/main/docs/running/sidecar.md)
86
+ and [A remote server](https://github.com/tinyshed/tinystore/blob/main/docs/running/server.md)
87
+ explain each one.
179
88
 
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
89
+ ## The command line
185
90
 
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
91
+ The package also installs the `tinystore` command. It shows what a store
92
+ contains and follows its logs while your program runs:
191
93
 
192
- const worker = store.records.lines('worker') // another program's output, cut anywhere
193
- for await (const chunk of child.stdout) worker.write(chunk)
94
+ ```sh
95
+ bunx @tinyshed/tinystore status ./data # each engine's size, and who serves the directory
96
+ bunx @tinyshed/tinystore logs ./data -f # the application's logs, as they arrive
97
+ claude mcp add tinystore -- bunx @tinyshed/tinystore mcp ./data # read-only access for an AI agent
194
98
  ```
195
99
 
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:
100
+ See [The command line](https://github.com/tinyshed/tinystore/blob/main/docs/running/cli.md)
101
+ for every command.
210
102
 
211
- ```ts
212
- import { logger } from '@tinyshed/tinystore'
213
-
214
- const log = logger('app', { redact: ['password'] }) // the console alone, nothing kept
215
- const db = log.with({ module: 'db' })
216
- ```
103
+ ## Documentation
217
104
 
218
- ## metrics
105
+ - [Getting started](https://github.com/tinyshed/tinystore/blob/main/docs/getting-started.md): install it and write a first program
106
+ - [A tour](https://github.com/tinyshed/tinystore/blob/main/docs/tour.md): every engine on one page
107
+ - [The guides](https://github.com/tinyshed/tinystore/blob/main/docs/README.md): a page per feature, each example in Bun, Python and Go
108
+ - [Bun and Node API](https://github.com/tinyshed/tinystore/blob/main/docs/reference/bun.md): every call, by engine
219
109
 
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
- ```
110
+ ## License
232
111
 
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.
112
+ Apache-2.0.
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.2",
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.2",
34
+ "@tinyshed/tinystore-darwin-x64": "0.1.0-rc.2",
35
+ "@tinyshed/tinystore-linux-arm64": "0.1.0-rc.2",
36
+ "@tinyshed/tinystore-linux-x64": "0.1.0-rc.2",
37
+ "@tinyshed/tinystore-win32-arm64": "0.1.0-rc.2",
38
+ "@tinyshed/tinystore-win32-x64": "0.1.0-rc.2"
39
39
  }
40
40
  }