@tinyshed/tinystore 0.1.0-rc.5 → 0.1.0-rc.7
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 +37 -37
- package/bin/tinystore.js +12 -1
- package/dist/backup.d.ts +33 -0
- package/dist/backup.js +49 -0
- package/dist/blobs.d.ts +160 -79
- package/dist/blobs.js +510 -217
- package/dist/channels.d.ts +90 -0
- package/dist/channels.js +291 -0
- package/dist/clock.js +3 -3
- package/dist/config.d.ts +209 -86
- package/dist/config.js +581 -538
- package/dist/connection.d.ts +64 -2
- package/dist/connection.js +201 -16
- package/dist/console.d.ts +27 -3
- package/dist/console.js +165 -12
- package/dist/dotenv.d.ts +7 -0
- package/dist/dotenv.js +79 -0
- package/dist/errors.d.ts +61 -1
- package/dist/errors.js +81 -1
- package/dist/handles.d.ts +44 -2
- package/dist/handles.js +81 -2
- package/dist/index.d.ts +17 -11
- package/dist/index.js +5 -3
- package/dist/instruments.d.ts +177 -0
- package/dist/instruments.js +819 -0
- package/dist/jobs.d.ts +335 -239
- package/dist/jobs.js +716 -536
- package/dist/json.d.ts +2 -0
- package/dist/json.js +122 -0
- package/dist/kv.d.ts +130 -243
- package/dist/kv.js +273 -640
- package/dist/limits.d.ts +80 -0
- package/dist/limits.js +139 -0
- package/dist/locks.d.ts +62 -0
- package/dist/locks.js +237 -0
- package/dist/logger.d.ts +45 -9
- package/dist/logger.js +150 -38
- package/dist/metrics.d.ts +210 -209
- package/dist/metrics.js +319 -556
- package/dist/once.d.ts +19 -18
- package/dist/once.js +74 -63
- package/dist/query.d.ts +181 -0
- package/dist/query.js +788 -0
- package/dist/records.d.ts +241 -150
- package/dist/records.js +507 -291
- package/dist/runtime/addon.d.ts +14 -0
- package/dist/runtime/addon.js +69 -0
- package/dist/runtime/bun.js +5 -7
- package/dist/runtime/node.js +5 -7
- package/dist/runtime/pipe.d.ts +17 -0
- package/dist/runtime/pipe.js +133 -0
- package/dist/runtime/shared.d.ts +6 -0
- package/dist/runtime/shared.js +19 -0
- package/dist/runtime.d.ts +5 -2
- package/dist/search.d.ts +189 -0
- package/dist/search.js +281 -0
- package/dist/session.d.ts +31 -3
- package/dist/session.js +153 -41
- package/dist/sql.d.ts +228 -78
- package/dist/sql.js +745 -240
- package/dist/store.d.ts +244 -24
- package/dist/store.js +270 -67
- package/dist/time.d.ts +5 -1
- package/dist/time.js +22 -2
- package/dist/tx.d.ts +61 -0
- package/dist/tx.js +314 -0
- package/dist/wire/codec.d.ts +23 -7
- package/dist/wire/codec.js +56 -35
- package/dist/wire/frame.d.ts +2 -0
- package/dist/wire/frame.js +31 -14
- package/dist/wire/messages.d.ts +259 -0
- package/dist/wire/messages.js +22 -0
- package/dist/wire/msgpack.d.ts +49 -1
- package/dist/wire/msgpack.js +293 -56
- package/dist/wire/protocol.d.ts +2683 -0
- package/dist/wire/protocol.js +10846 -0
- package/package.json +39 -38
- package/src/backup.ts +81 -0
- package/src/blobs.ts +678 -301
- package/src/channels.ts +377 -0
- package/src/clock.ts +4 -4
- package/src/config.ts +902 -612
- package/src/connection.ts +279 -21
- package/src/console.ts +180 -12
- package/src/dotenv.ts +82 -0
- package/src/errors.ts +105 -0
- package/src/handles.ts +157 -8
- package/src/index.ts +158 -52
- package/src/instruments.ts +1042 -0
- package/src/jobs.ts +1017 -733
- package/src/json.ts +133 -0
- package/src/kv.ts +424 -847
- package/src/limits.ts +202 -0
- package/src/locks.ts +320 -0
- package/src/logger.ts +209 -40
- package/src/metrics.ts +557 -752
- package/src/once.ts +86 -83
- package/src/query.ts +1005 -0
- package/src/records.ts +795 -418
- package/src/runtime/addon.ts +99 -0
- package/src/runtime/bun.ts +5 -7
- package/src/runtime/node.ts +5 -7
- package/src/runtime/pipe.ts +178 -0
- package/src/runtime/shared.ts +20 -0
- package/src/runtime.ts +5 -2
- package/src/search.ts +480 -0
- package/src/session.ts +187 -41
- package/src/sql.ts +993 -306
- package/src/store.ts +473 -78
- package/src/time.ts +48 -3
- package/src/tx.ts +426 -0
- package/src/wire/codec.ts +78 -37
- package/src/wire/frame.ts +44 -14
- package/src/wire/messages.ts +25 -0
- package/src/wire/msgpack.ts +327 -56
- package/src/wire/protocol.ts +11709 -0
- package/dist/limiter.d.ts +0 -45
- package/dist/limiter.js +0 -68
- package/dist/quota.d.ts +0 -44
- package/dist/quota.js +0 -98
- package/src/limiter.ts +0 -99
- package/src/quota.ts +0 -137
package/README.md
CHANGED
|
@@ -9,17 +9,18 @@ one. Every call, by engine, is in docs/reference/bun.md.
|
|
|
9
9
|
|
|
10
10
|
<!-- landing:headline -->
|
|
11
11
|
|
|
12
|
-
**A small storage runtime for applications.** SQL, key-value state, durable jobs, files,
|
|
12
|
+
**A small storage runtime for applications.** SQL, key-value state, durable jobs, files, search, logs and metrics in one directory, with one lifecycle, one memory budget and one backup.
|
|
13
13
|
|
|
14
14
|
<!-- /landing:headline -->
|
|
15
15
|
|
|
16
|
-
> **
|
|
17
|
-
>
|
|
16
|
+
> **Not released yet.** Until `v0.1.0`, the API may still change, and a file
|
|
17
|
+
> written by one version may not open in the next.
|
|
18
18
|
|
|
19
19
|
The SDK starts a small `tinystore` server next to your program, called the
|
|
20
|
-
sidecar, and talks to it over a local connection
|
|
21
|
-
|
|
22
|
-
|
|
20
|
+
sidecar, and talks to it over a local connection, so that several processes
|
|
21
|
+
share one store. With `embedded: true` the core runs inside your process
|
|
22
|
+
instead. The server and the core come with the package, so there is nothing
|
|
23
|
+
else to install. It runs on Bun 1.4 and Node 22 or later.
|
|
23
24
|
|
|
24
25
|
<!-- landing:sample -->
|
|
25
26
|
|
|
@@ -28,25 +29,20 @@ import { open } from '@tinyshed/tinystore'
|
|
|
28
29
|
|
|
29
30
|
await using store = await open('./data')
|
|
30
31
|
|
|
31
|
-
const db = await store.
|
|
32
|
-
migrations: { '0001_users.sql': 'create table users (id integer primary key, name text)' },
|
|
33
|
-
})
|
|
32
|
+
const db = await store.database('app', { migrations: './migrations' })
|
|
34
33
|
await db.exec`insert into users (id, name) values (${42}, ${'Ada'})`
|
|
35
34
|
|
|
36
|
-
const sessions = store.
|
|
37
|
-
await sessions.
|
|
35
|
+
const sessions = store.bucket<Session>('sessions', { idle: '30d' })
|
|
36
|
+
await sessions.set(digest(token), { userId: 42 })
|
|
38
37
|
|
|
39
|
-
const emails = store.
|
|
40
|
-
await emails.
|
|
38
|
+
const emails = store.queue<Email>('emails')
|
|
39
|
+
await emails.add({ to: 'ada@example.com' })
|
|
41
40
|
|
|
42
|
-
const
|
|
43
|
-
await
|
|
41
|
+
const avatars = store.files('avatars')
|
|
42
|
+
await avatars.put('42.png', Bun.file('avatar.png'))
|
|
44
43
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
const signups = store.metrics.counter('signups_total')
|
|
49
|
-
signups.inc()
|
|
44
|
+
store.logger('api').info('user created', { userId: 42 })
|
|
45
|
+
store.metrics.counter('signups_total').inc()
|
|
50
46
|
```
|
|
51
47
|
|
|
52
48
|
```sh
|
|
@@ -63,14 +59,19 @@ contains. With npm, pnpm or Yarn, install it as `npm install @tinyshed/tinystore
|
|
|
63
59
|
|
|
64
60
|
<!-- landing:engines -->
|
|
65
61
|
|
|
66
|
-
|
|
|
67
|
-
|
|
68
|
-
| [SQL](https://github.com/tinyshed/tinystore/blob/main/docs/sql/README.md)
|
|
69
|
-
| [KV](https://github.com/tinyshed/tinystore/blob/main/docs/kv/README.md)
|
|
70
|
-
| [Jobs](https://github.com/tinyshed/tinystore/blob/main/docs/jobs/README.md)
|
|
71
|
-
| [Blobs](https://github.com/tinyshed/tinystore/blob/main/docs/blobs/README.md)
|
|
72
|
-
| [
|
|
73
|
-
| [
|
|
62
|
+
| | | |
|
|
63
|
+
|--------------------------------------------------------------------------------------------|-------------------|-------------------------------------------------------------------------|
|
|
64
|
+
| [SQL](https://github.com/tinyshed/tinystore/blob/main/docs/guides/sql/README.md) | Relational state | Your own SQLite databases: checked migrations, a query builder. |
|
|
65
|
+
| [KV](https://github.com/tinyshed/tinystore/blob/main/docs/guides/kv/README.md) | Application state | Values with expiry and versions; counters, rate limits, quotas, `once`. |
|
|
66
|
+
| [Jobs](https://github.com/tinyshed/tinystore/blob/main/docs/guides/jobs/README.md) | Background work | Work that runs at its time: retries, steps, schedules, limits. |
|
|
67
|
+
| [Blobs](https://github.com/tinyshed/tinystore/blob/main/docs/guides/blobs/README.md) | Files | Files by path, written whole or not at all, checked when read. |
|
|
68
|
+
| [Search](https://github.com/tinyshed/tinystore/blob/main/docs/guides/search/README.md) | Words and vectors | Indexes of documents or of your tables, by words, by meaning, or both. |
|
|
69
|
+
| [Channels](https://github.com/tinyshed/tinystore/blob/main/docs/guides/channels/README.md) | Messages | Messages to whoever listens now, sent from a transaction at its commit. |
|
|
70
|
+
| [Locks](https://github.com/tinyshed/tinystore/blob/main/docs/guides/locks/README.md) | Coordination | Locks and semaphores with fences, across processes and connections. |
|
|
71
|
+
| [Config](https://github.com/tinyshed/tinystore/blob/main/docs/guides/config/README.md) | Settings | Files and the environment in layers; secrets; settings changed live. |
|
|
72
|
+
| [Records](https://github.com/tinyshed/tinystore/blob/main/docs/guides/records/README.md) | Logs and events | Read back by time, level, fields and text; followed as they arrive. |
|
|
73
|
+
| [Metrics](https://github.com/tinyshed/tinystore/blob/main/docs/guides/metrics/README.md) | Time series | Samples kept bit for bit, answered exactly. |
|
|
74
|
+
| [Backup](https://github.com/tinyshed/tinystore/blob/main/docs/guides/backup/README.md) | The whole store | One checked zip of every engine, taken while it runs. |
|
|
74
75
|
|
|
75
76
|
<!-- /landing:engines -->
|
|
76
77
|
|
|
@@ -84,9 +85,8 @@ await using alone = await open('./data', { private: true }) // a server for this
|
|
|
84
85
|
await using remote = await connect('tls://db.internal:7070', { token })
|
|
85
86
|
```
|
|
86
87
|
|
|
87
|
-
[
|
|
88
|
-
|
|
89
|
-
explain each one.
|
|
88
|
+
[One directory, many engines](https://github.com/tinyshed/tinystore/blob/main/docs/handbook/start/directory.md#four-ways-to-open-a-store)
|
|
89
|
+
explains each one.
|
|
90
90
|
|
|
91
91
|
## The command line
|
|
92
92
|
|
|
@@ -99,15 +99,15 @@ bunx @tinyshed/tinystore logs ./data -f # the applicatio
|
|
|
99
99
|
claude mcp add tinystore -- bunx @tinyshed/tinystore mcp ./data # read-only access for an AI agent
|
|
100
100
|
```
|
|
101
101
|
|
|
102
|
-
See [
|
|
103
|
-
for
|
|
102
|
+
See [Your first store](https://github.com/tinyshed/tinystore/blob/main/docs/handbook/start/first-store.md#look-inside)
|
|
103
|
+
for the commands at work.
|
|
104
104
|
|
|
105
105
|
## Documentation
|
|
106
106
|
|
|
107
|
-
- [
|
|
108
|
-
- [
|
|
109
|
-
- [The
|
|
110
|
-
- [
|
|
107
|
+
- [Your first store](https://github.com/tinyshed/tinystore/blob/main/docs/handbook/start/first-store.md): install it and write a first program
|
|
108
|
+
- [The chat we build](https://github.com/tinyshed/tinystore/blob/main/docs/handbook/start/chat.md): the application the book builds
|
|
109
|
+
- [The documentation](https://github.com/tinyshed/tinystore/blob/main/docs/README.md): the book, each example in TypeScript, Python, Go and Rust
|
|
110
|
+
- [API reference](https://github.com/tinyshed/tinystore/blob/main/docs/reference/api.md): every call, by engine
|
|
111
111
|
|
|
112
112
|
## License
|
|
113
113
|
|
package/bin/tinystore.js
CHANGED
|
@@ -5,11 +5,22 @@
|
|
|
5
5
|
// nothing else installed. Plain JavaScript, so that Node and Bun both run it.
|
|
6
6
|
|
|
7
7
|
import { spawn } from 'node:child_process'
|
|
8
|
+
import { readdirSync } from 'node:fs'
|
|
8
9
|
import { createRequire } from 'node:module'
|
|
9
10
|
import { constants } from 'node:os'
|
|
10
11
|
|
|
11
12
|
const executable = process.platform === 'win32' ? 'tinystore.exe' : 'tinystore'
|
|
12
|
-
|
|
13
|
+
// Linux's package is musl's where its loader is in /lib, as npm chose it by libc
|
|
14
|
+
const musl = process.platform === 'linux' && runsOnMusl()
|
|
15
|
+
const platform = `@tinyshed/tinystore-${process.platform}-${process.arch}${musl ? '-musl' : ''}`
|
|
16
|
+
|
|
17
|
+
function runsOnMusl() {
|
|
18
|
+
try {
|
|
19
|
+
return readdirSync('/lib').some(name => name.startsWith('ld-musl-'))
|
|
20
|
+
} catch {
|
|
21
|
+
return false
|
|
22
|
+
}
|
|
23
|
+
}
|
|
13
24
|
|
|
14
25
|
function packagedBinary() {
|
|
15
26
|
try {
|
package/dist/backup.d.ts
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import type { Link } from './connection.ts';
|
|
2
|
+
/** What a backup takes beside every engine's files. */
|
|
3
|
+
export interface BackupOptions {
|
|
4
|
+
/**
|
|
5
|
+
* files of the program's it includes, by their paths inside the store's
|
|
6
|
+
* directory, such as 'secret.key', which a restore puts back where they
|
|
7
|
+
* were: a backup holds none unless named
|
|
8
|
+
*/
|
|
9
|
+
include?: readonly string[];
|
|
10
|
+
/**
|
|
11
|
+
* includes the store's encryption key, as it is, which a backup leaves
|
|
12
|
+
* out otherwise: the zip is not encrypted, so a backup with the key opens
|
|
13
|
+
* every value it holds
|
|
14
|
+
*/
|
|
15
|
+
includeEncryptionKey?: boolean;
|
|
16
|
+
}
|
|
17
|
+
/** What a backup holds. */
|
|
18
|
+
export interface Backup {
|
|
19
|
+
/** the files, the engines' and those it was told to take */
|
|
20
|
+
files: number;
|
|
21
|
+
/** their bytes, the zip's own fields aside */
|
|
22
|
+
bytes: number;
|
|
23
|
+
/**
|
|
24
|
+
* the store seals values with an encryption key the backup does not
|
|
25
|
+
* hold: they open with that key alone, kept apart
|
|
26
|
+
*/
|
|
27
|
+
keyLeftOut: boolean;
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Writes a backup of the store `link` reaches to `path`, beside it first:
|
|
31
|
+
* a connection lost on the way makes it again from its start.
|
|
32
|
+
*/
|
|
33
|
+
export declare function backup(link: Link, path: string, options: BackupOptions): Promise<Backup>;
|
package/dist/backup.js
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
// A backup of the whole store, as docs/guides/backup/README.md has it: one zip of every
|
|
2
|
+
// engine that the server writes while the store keeps working and sends in
|
|
3
|
+
// pieces, written beside the name the program gives and renamed once whole,
|
|
4
|
+
// so that a backup that fails leaves no zip.
|
|
5
|
+
import { open, rename, rm } from 'node:fs/promises';
|
|
6
|
+
import { BackupPiece, BackupWrite, BackupWritten, methods } from './wire/protocol.js';
|
|
7
|
+
const nothing = new Uint8Array();
|
|
8
|
+
/**
|
|
9
|
+
* Writes a backup of the store `link` reaches to `path`, beside it first:
|
|
10
|
+
* a connection lost on the way makes it again from its start.
|
|
11
|
+
*/
|
|
12
|
+
export async function backup(link, path, options) {
|
|
13
|
+
const partial = `${path}.${process.pid}.part`;
|
|
14
|
+
const asked = BackupWrite.encode({
|
|
15
|
+
include: [...(options.include ?? [])],
|
|
16
|
+
includeEncryptionKey: options.includeEncryptionKey === true,
|
|
17
|
+
});
|
|
18
|
+
try {
|
|
19
|
+
const backed = await link.run('read', async (connection) => {
|
|
20
|
+
const file = await open(partial, 'w');
|
|
21
|
+
try {
|
|
22
|
+
const stream = await connection.session.open(methods['backup.write'], asked, true);
|
|
23
|
+
await stream.next();
|
|
24
|
+
for (;;) {
|
|
25
|
+
const event = await stream.next();
|
|
26
|
+
if (event.end) {
|
|
27
|
+
await file.sync();
|
|
28
|
+
return BackupWritten.decode(event.body);
|
|
29
|
+
}
|
|
30
|
+
stream.consumed(event.body.length);
|
|
31
|
+
await file.write(BackupPiece.decode(event.body).bytes ?? nothing);
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
finally {
|
|
35
|
+
await file.close();
|
|
36
|
+
}
|
|
37
|
+
});
|
|
38
|
+
await rename(partial, path);
|
|
39
|
+
return {
|
|
40
|
+
files: Number(backed.files ?? 0),
|
|
41
|
+
bytes: Number(backed.bytes ?? 0),
|
|
42
|
+
keyLeftOut: backed.keyLeftOut === true,
|
|
43
|
+
};
|
|
44
|
+
}
|
|
45
|
+
catch (err) {
|
|
46
|
+
await rm(partial, { force: true });
|
|
47
|
+
throw err;
|
|
48
|
+
}
|
|
49
|
+
}
|
package/dist/blobs.d.ts
CHANGED
|
@@ -1,98 +1,179 @@
|
|
|
1
1
|
import { type Link } from './connection.ts';
|
|
2
|
-
import { type
|
|
3
|
-
import { type Duration
|
|
4
|
-
|
|
5
|
-
export
|
|
6
|
-
|
|
7
|
-
|
|
2
|
+
import { type Stream } from './session.ts';
|
|
3
|
+
import { type Duration } from './time.ts';
|
|
4
|
+
/** A size in bytes: a number, or text in binary units, 64KiB or 2GiB; '2GB' does not compile. */
|
|
5
|
+
export type Size = number | `${number}${'KiB' | 'MiB' | 'GiB' | 'TiB'}`;
|
|
6
|
+
export interface FilesOptions {
|
|
7
|
+
/** the term of every file written without its own; not a ceiling */
|
|
8
|
+
ttl?: Duration | undefined;
|
|
9
|
+
/** the largest file a write may leave: past it, a write is refused and leaves nothing */
|
|
10
|
+
maxFileSize?: Size | undefined;
|
|
11
|
+
}
|
|
12
|
+
/** What a file carries: what serving it needs. */
|
|
13
|
+
export interface FileInfo {
|
|
14
|
+
/** its path within the folder it was asked from */
|
|
15
|
+
path: string;
|
|
8
16
|
size: number;
|
|
9
|
-
/**
|
|
17
|
+
/** the SHA-256 of its bytes in hex, quoted, as an HTTP ETag is */
|
|
10
18
|
etag: string;
|
|
11
|
-
contentType: string
|
|
12
|
-
|
|
13
|
-
/** undefined for
|
|
19
|
+
contentType: string;
|
|
20
|
+
lastModified: Date;
|
|
21
|
+
/** undefined for a file that does not expire */
|
|
14
22
|
expires: Date | undefined;
|
|
15
23
|
meta: Record<string, string>;
|
|
16
24
|
}
|
|
17
|
-
export interface
|
|
18
|
-
contentType?: string;
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
ttl?: Duration;
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
25
|
+
export interface FileOptions {
|
|
26
|
+
contentType?: string | undefined;
|
|
27
|
+
meta?: Record<string, string> | undefined;
|
|
28
|
+
/** the file's own term, from this write */
|
|
29
|
+
ttl?: Duration | undefined;
|
|
30
|
+
/** the ETag of the one file this write may replace: another is ConflictError */
|
|
31
|
+
ifMatch?: string | undefined;
|
|
32
|
+
/** the body's length: one longer or shorter is refused and leaves nothing */
|
|
33
|
+
size?: number | undefined;
|
|
34
|
+
signal?: AbortSignal | undefined;
|
|
27
35
|
}
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
36
|
+
/** What a write takes: text, bytes, a Blob or a file, or a stream of bytes. */
|
|
37
|
+
export type Body = string | Uint8Array | ArrayBuffer | Blob | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
|
|
38
|
+
export interface FileListOptions {
|
|
39
|
+
/** text within the folder: 'photos/1' finds photos/10.jpg too */
|
|
40
|
+
prefix?: string | undefined;
|
|
41
|
+
/** a page's next */
|
|
42
|
+
after?: string | undefined;
|
|
43
|
+
/** 1000 at most, and when absent */
|
|
44
|
+
limit?: number | undefined;
|
|
32
45
|
}
|
|
33
|
-
/**
|
|
34
|
-
export
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
readonly body: ReadableStream<Uint8Array>;
|
|
39
|
-
bytes(): Promise<Uint8Array>;
|
|
40
|
-
text(): Promise<string>;
|
|
41
|
-
json(): Promise<unknown>;
|
|
46
|
+
/** A page of a folder's files in the byte order of their paths, and where the next starts. */
|
|
47
|
+
export interface FilePage {
|
|
48
|
+
files: FileInfo[];
|
|
49
|
+
/** undefined on the last page */
|
|
50
|
+
next: string | undefined;
|
|
42
51
|
}
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
}
|
|
51
|
-
/** A bucket's objects under one folder of owners, the root when there are none. */
|
|
52
|
-
export declare class BlobBucket {
|
|
52
|
+
/** Files as `store.files` opens them. */
|
|
53
|
+
export declare function openFiles(link: Link, name: string, options?: FilesOptions): Files;
|
|
54
|
+
/**
|
|
55
|
+
* A named set of files by path, or a folder of it, whose calls are the
|
|
56
|
+
* folder's: a path in it is the folder's segments and then its own.
|
|
57
|
+
*/
|
|
58
|
+
export declare class Files {
|
|
53
59
|
#private;
|
|
54
60
|
readonly name: string;
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
of
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
/**
|
|
61
|
+
/** Files come from `store.files`. */
|
|
62
|
+
constructor(link: Link, name: string, open: Uint8Array, folder: string[]);
|
|
63
|
+
/** The folder of these segments, one each: `folder('users', 42)` is users/42, never users/420. */
|
|
64
|
+
folder(...segments: (string | number | bigint)[]): Files;
|
|
65
|
+
/**
|
|
66
|
+
* Writes the file whole and replaces whatever the path held, returning
|
|
67
|
+
* once it is on disk as the store's durability says. Nobody sees half of
|
|
68
|
+
* it, while it is written or after a crash.
|
|
69
|
+
*/
|
|
70
|
+
put(path: string, body: Body, options?: FileOptions): Promise<FileInfo>;
|
|
71
|
+
/** Writes the file only where the path holds none, and says whether it did. */
|
|
72
|
+
create(path: string, body: Body, options?: Omit<FileOptions, 'ifMatch'>): Promise<boolean>;
|
|
73
|
+
/**
|
|
74
|
+
* What the file carries, and its bytes: a file up to about a megabyte comes
|
|
75
|
+
* with them, and a larger one's are read when they are read, on its ETag,
|
|
76
|
+
* as S3's GET with If-Match reads them. Undefined when the path holds none.
|
|
77
|
+
*/
|
|
78
|
+
get(path: string): Promise<StoredFile | undefined>;
|
|
79
|
+
/** What the file carries and none of its bytes; undefined when the path holds none. */
|
|
80
|
+
head(path: string): Promise<FileInfo | undefined>;
|
|
81
|
+
/** Deletes the file, or with ifMatch only that version of it; no file there is not an error. */
|
|
82
|
+
delete(path: string, options?: {
|
|
83
|
+
ifMatch?: string | undefined;
|
|
84
|
+
}): Promise<void>;
|
|
85
|
+
/**
|
|
86
|
+
* A copy at `to` that shares the bytes, which are not copied. A file at
|
|
87
|
+
* `to` is ConflictError unless ifMatch names the version to replace.
|
|
88
|
+
*/
|
|
89
|
+
copy(from: string, to: string, options?: {
|
|
90
|
+
ifMatch?: string | undefined;
|
|
91
|
+
}): Promise<FileInfo>;
|
|
92
|
+
/**
|
|
93
|
+
* The file moved to `to` in one write: a file there is ConflictError
|
|
94
|
+
* unless ifMatch names the version to replace, and none at `from` NotFoundError.
|
|
95
|
+
*/
|
|
96
|
+
rename(from: string, to: string, options?: {
|
|
97
|
+
ifMatch?: string | undefined;
|
|
98
|
+
}): Promise<FileInfo>;
|
|
99
|
+
/** Sets when the file expires, a span from now or a moment; says whether there was a file. */
|
|
100
|
+
expire(path: string, after: Duration | Date): Promise<boolean>;
|
|
101
|
+
/** A page of the files in the folder and in the folders in it, in the byte order of their paths. */
|
|
102
|
+
list(options?: FileListOptions): Promise<FilePage>;
|
|
103
|
+
/** Every file of the folder, a page at a time, holding nothing between pages. */
|
|
104
|
+
all(options?: {
|
|
105
|
+
prefix?: string | undefined;
|
|
106
|
+
}): AsyncGenerator<FileInfo>;
|
|
107
|
+
/** The files in the folder and their bytes, as it is now: it counts, it does not limit. */
|
|
66
108
|
usage(): Promise<{
|
|
67
|
-
|
|
68
|
-
|
|
109
|
+
count: number;
|
|
110
|
+
size: number;
|
|
69
111
|
}>;
|
|
70
|
-
/** Removes
|
|
112
|
+
/** Removes the folder's every file and every folder in it, at once for every reader. */
|
|
71
113
|
clear(): Promise<void>;
|
|
72
|
-
/** A page of the objects under this folder, its folders included, in the byte order of their paths. */
|
|
73
|
-
scan(options?: {
|
|
74
|
-
prefix?: string;
|
|
75
|
-
after?: string;
|
|
76
|
-
limit?: number;
|
|
77
|
-
}): Promise<Page<BlobObject, string>>;
|
|
78
|
-
all(options?: {
|
|
79
|
-
prefix?: string;
|
|
80
|
-
limit?: number;
|
|
81
|
-
}): AsyncGenerator<BlobObject>;
|
|
82
114
|
/**
|
|
83
|
-
*
|
|
84
|
-
*
|
|
85
|
-
*
|
|
115
|
+
* Begins a file written a piece at a time, which appears at `commit` and
|
|
116
|
+
* never before: `await using upload = await files.upload(path)`, and
|
|
117
|
+
* leaving the block without commit aborts it.
|
|
118
|
+
*/
|
|
119
|
+
upload(path: string, options?: FileOptions): Promise<Upload>;
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* A file written a piece at a time, as `files.upload` begins it: bytes go in
|
|
123
|
+
* with `write`, the file appears at `commit` and never before, and an upload
|
|
124
|
+
* that ends otherwise leaves nothing.
|
|
125
|
+
*/
|
|
126
|
+
export declare class Upload implements AsyncDisposable {
|
|
127
|
+
#private;
|
|
128
|
+
/** Uploads come from `files.upload`. */
|
|
129
|
+
constructor(stream: Stream, piece: number, signal: AbortSignal | undefined);
|
|
130
|
+
/** Takes bytes, text as UTF-8, waiting while the server catches up. */
|
|
131
|
+
write(bytes: Uint8Array | string): Promise<void>;
|
|
132
|
+
/**
|
|
133
|
+
* Publishes the file whole, replacing what the path held as `put` does,
|
|
134
|
+
* once it is on disk as the store's durability says.
|
|
86
135
|
*/
|
|
87
|
-
|
|
136
|
+
commit(): Promise<FileInfo>;
|
|
137
|
+
/** Ends the upload, which leaves nothing; after `commit` it does nothing. */
|
|
138
|
+
abort(): Promise<void>;
|
|
139
|
+
[Symbol.asyncDispose](): Promise<void>;
|
|
140
|
+
}
|
|
141
|
+
/**
|
|
142
|
+
* Bytes of a file, read when they are read, as a Blob's are: `stream()`, or
|
|
143
|
+
* all of them with `bytes()`, `text()`, `json()` or `arrayBuffer()`, which
|
|
144
|
+
* hold them in memory. Each read is a read of its own.
|
|
145
|
+
*/
|
|
146
|
+
export declare class FileBytes {
|
|
147
|
+
#private;
|
|
148
|
+
readonly size: number;
|
|
149
|
+
/** File bytes come from `files.get` and `slice`. */
|
|
150
|
+
constructor(size: number, stream: () => ReadableStream<Uint8Array>);
|
|
151
|
+
/** Its bytes as they come, the credit of each given back once it is taken. */
|
|
152
|
+
stream(): ReadableStream<Uint8Array>;
|
|
153
|
+
bytes(): Promise<Uint8Array<ArrayBuffer>>;
|
|
154
|
+
arrayBuffer(): Promise<ArrayBuffer>;
|
|
155
|
+
text(): Promise<string>;
|
|
156
|
+
json(): Promise<unknown>;
|
|
157
|
+
}
|
|
158
|
+
/**
|
|
159
|
+
* A file as `get` found it: what it carries, and its bytes. A whole read is
|
|
160
|
+
* checked against its SHA-256 and fails CorruptError before its last bytes
|
|
161
|
+
* when they changed; `slice` reads a range, which is not checked.
|
|
162
|
+
*/
|
|
163
|
+
export declare class StoredFile extends FileBytes implements FileInfo {
|
|
164
|
+
#private;
|
|
165
|
+
readonly path: string;
|
|
166
|
+
readonly etag: string;
|
|
167
|
+
readonly contentType: string;
|
|
168
|
+
readonly lastModified: Date;
|
|
169
|
+
readonly expires: Date | undefined;
|
|
170
|
+
readonly meta: Record<string, string>;
|
|
171
|
+
/** Stored files come from `files.get`. */
|
|
172
|
+
constructor(info: FileInfo, whole: Uint8Array | undefined, read: (offset?: number, length?: number) => ReadableStream<Uint8Array>);
|
|
88
173
|
/**
|
|
89
|
-
*
|
|
90
|
-
* and
|
|
91
|
-
*
|
|
174
|
+
* A range of its bytes, as Blob.slice takes one: an end left out is the
|
|
175
|
+
* file's, and a negative place counts back from it, so `slice(-500)` is the
|
|
176
|
+
* last 500 bytes.
|
|
92
177
|
*/
|
|
93
|
-
|
|
94
|
-
offset?: number;
|
|
95
|
-
length?: number;
|
|
96
|
-
signal?: AbortSignal;
|
|
97
|
-
}): Promise<Download | undefined>;
|
|
178
|
+
slice(start?: number, end?: number): FileBytes;
|
|
98
179
|
}
|