@tinyshed/tinystore 0.1.0-rc.5 → 0.1.0-rc.6

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 (122) hide show
  1. package/README.md +37 -37
  2. package/bin/tinystore.js +12 -1
  3. package/dist/backup.d.ts +33 -0
  4. package/dist/backup.js +49 -0
  5. package/dist/blobs.d.ts +160 -79
  6. package/dist/blobs.js +510 -217
  7. package/dist/channels.d.ts +90 -0
  8. package/dist/channels.js +291 -0
  9. package/dist/clock.js +3 -3
  10. package/dist/config.d.ts +209 -86
  11. package/dist/config.js +581 -538
  12. package/dist/connection.d.ts +64 -2
  13. package/dist/connection.js +201 -16
  14. package/dist/console.d.ts +27 -3
  15. package/dist/console.js +165 -12
  16. package/dist/dotenv.d.ts +7 -0
  17. package/dist/dotenv.js +79 -0
  18. package/dist/errors.d.ts +61 -1
  19. package/dist/errors.js +81 -1
  20. package/dist/handles.d.ts +44 -2
  21. package/dist/handles.js +81 -2
  22. package/dist/index.d.ts +17 -11
  23. package/dist/index.js +5 -3
  24. package/dist/instruments.d.ts +177 -0
  25. package/dist/instruments.js +819 -0
  26. package/dist/jobs.d.ts +335 -239
  27. package/dist/jobs.js +716 -536
  28. package/dist/json.d.ts +2 -0
  29. package/dist/json.js +122 -0
  30. package/dist/kv.d.ts +130 -243
  31. package/dist/kv.js +273 -640
  32. package/dist/limits.d.ts +80 -0
  33. package/dist/limits.js +139 -0
  34. package/dist/locks.d.ts +62 -0
  35. package/dist/locks.js +237 -0
  36. package/dist/logger.d.ts +45 -9
  37. package/dist/logger.js +150 -38
  38. package/dist/metrics.d.ts +210 -209
  39. package/dist/metrics.js +319 -556
  40. package/dist/once.d.ts +19 -18
  41. package/dist/once.js +74 -63
  42. package/dist/query.d.ts +181 -0
  43. package/dist/query.js +788 -0
  44. package/dist/records.d.ts +241 -150
  45. package/dist/records.js +507 -291
  46. package/dist/runtime/addon.d.ts +14 -0
  47. package/dist/runtime/addon.js +69 -0
  48. package/dist/runtime/bun.js +5 -7
  49. package/dist/runtime/node.js +5 -7
  50. package/dist/runtime/pipe.d.ts +17 -0
  51. package/dist/runtime/pipe.js +133 -0
  52. package/dist/runtime/shared.d.ts +6 -0
  53. package/dist/runtime/shared.js +19 -0
  54. package/dist/runtime.d.ts +5 -2
  55. package/dist/search.d.ts +189 -0
  56. package/dist/search.js +281 -0
  57. package/dist/session.d.ts +31 -3
  58. package/dist/session.js +153 -41
  59. package/dist/sql.d.ts +228 -78
  60. package/dist/sql.js +745 -240
  61. package/dist/store.d.ts +244 -24
  62. package/dist/store.js +270 -67
  63. package/dist/time.d.ts +5 -1
  64. package/dist/time.js +22 -2
  65. package/dist/tx.d.ts +61 -0
  66. package/dist/tx.js +314 -0
  67. package/dist/wire/codec.d.ts +23 -7
  68. package/dist/wire/codec.js +56 -35
  69. package/dist/wire/frame.d.ts +2 -0
  70. package/dist/wire/frame.js +31 -14
  71. package/dist/wire/messages.d.ts +259 -0
  72. package/dist/wire/messages.js +22 -0
  73. package/dist/wire/msgpack.d.ts +49 -1
  74. package/dist/wire/msgpack.js +293 -56
  75. package/dist/wire/protocol.d.ts +2683 -0
  76. package/dist/wire/protocol.js +10846 -0
  77. package/package.json +39 -38
  78. package/src/backup.ts +81 -0
  79. package/src/blobs.ts +678 -301
  80. package/src/channels.ts +377 -0
  81. package/src/clock.ts +4 -4
  82. package/src/config.ts +902 -612
  83. package/src/connection.ts +279 -21
  84. package/src/console.ts +180 -12
  85. package/src/dotenv.ts +82 -0
  86. package/src/errors.ts +105 -0
  87. package/src/handles.ts +157 -8
  88. package/src/index.ts +158 -52
  89. package/src/instruments.ts +1042 -0
  90. package/src/jobs.ts +1017 -733
  91. package/src/json.ts +133 -0
  92. package/src/kv.ts +424 -847
  93. package/src/limits.ts +202 -0
  94. package/src/locks.ts +320 -0
  95. package/src/logger.ts +209 -40
  96. package/src/metrics.ts +557 -752
  97. package/src/once.ts +86 -83
  98. package/src/query.ts +1005 -0
  99. package/src/records.ts +795 -418
  100. package/src/runtime/addon.ts +99 -0
  101. package/src/runtime/bun.ts +5 -7
  102. package/src/runtime/node.ts +5 -7
  103. package/src/runtime/pipe.ts +178 -0
  104. package/src/runtime/shared.ts +20 -0
  105. package/src/runtime.ts +5 -2
  106. package/src/search.ts +480 -0
  107. package/src/session.ts +187 -41
  108. package/src/sql.ts +993 -306
  109. package/src/store.ts +473 -78
  110. package/src/time.ts +48 -3
  111. package/src/tx.ts +426 -0
  112. package/src/wire/codec.ts +78 -37
  113. package/src/wire/frame.ts +44 -14
  114. package/src/wire/messages.ts +25 -0
  115. package/src/wire/msgpack.ts +327 -56
  116. package/src/wire/protocol.ts +11709 -0
  117. package/dist/limiter.d.ts +0 -45
  118. package/dist/limiter.js +0 -68
  119. package/dist/quota.d.ts +0 -44
  120. package/dist/quota.js +0 -98
  121. package/src/limiter.ts +0 -99
  122. 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, metrics and logs in one directory, with one lifecycle, one memory budget and one backup.
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
- > **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.
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. 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.
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.sql('app', {
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.kv.bucket<string>('sessions', { sliding: '30d' })
37
- await sessions.of('42').set('token', 'abc123')
35
+ const sessions = store.bucket<Session>('sessions', { idle: '30d' })
36
+ await sessions.set(digest(token), { userId: 42 })
38
37
 
39
- const emails = store.jobs.queue<{ to: string }>('emails')
40
- await emails.enqueue({ to: 'ada@example.com' })
38
+ const emails = store.queue<Email>('emails')
39
+ await emails.add({ to: 'ada@example.com' })
41
40
 
42
- const files = store.blobs.bucket('files')
43
- await files.put('avatars/42.png', Bun.file('avatar.png'))
41
+ const avatars = store.files('avatars')
42
+ await avatars.put('42.png', Bun.file('avatar.png'))
44
43
 
45
- const log = store.records.logger('api')
46
- log.event('user.created', { userId: 42 })
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) | 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. |
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
- [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.
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 [The command line](https://github.com/tinyshed/tinystore/blob/main/docs/running/cli.md)
103
- for every command.
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
- - [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
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
- const platform = `@tinyshed/tinystore-${process.platform}-${process.arch}`
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 {
@@ -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 Page } from './handles.ts';
3
- import { type Duration, type Time } from './time.ts';
4
- import type { Key } from './wire/codec.ts';
5
- export interface BlobObject {
6
- /** its path under the folder that returned it */
7
- key: string;
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
- /** quoted, as an HTTP header carries it: equal bytes, one ETag */
17
+ /** the SHA-256 of its bytes in hex, quoted, as an HTTP ETag is */
10
18
  etag: string;
11
- contentType: string | undefined;
12
- modified: Date;
13
- /** undefined for an object that does not expire */
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 WriteOptions {
18
- contentType?: string;
19
- /** replaces all of an object's meta; a copy keeps its source's when absent */
20
- meta?: Record<string, string>;
21
- ttl?: Duration;
22
- expireAt?: Time;
23
- /** writes only while the key holds a live object with one of these ETags, as If-Match spells them */
24
- ifMatch?: string;
25
- /** writes only where no live object is */
26
- ifNoneMatch?: boolean;
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
- export interface PutOptions extends WriteOptions {
29
- /** the body's length, when it cannot say itself: one that disagrees leaves nothing */
30
- size?: number;
31
- signal?: AbortSignal;
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
- /** What a put takes: bytes, text, a Blob or a file, or a stream of bytes. */
34
- export type Body = Uint8Array | ArrayBuffer | string | Blob | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
35
- /** An object being read: what it is, and its bytes as a stream to consume or cancel. */
36
- export interface Download extends BlobObject {
37
- /** its bytes; a whole read whose bytes changed ends with CorruptError before its last */
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
- export declare class Blobs {
44
- #private;
45
- constructor(link: Link);
46
- bucket(name: string, options?: {
47
- defaultTtl?: Duration;
48
- maxSize?: number;
49
- }): BlobBucket;
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
- constructor(link: Link, name: string, open: Uint8Array, owners: (string | Uint8Array)[]);
56
- /** The folder below this one that the owners name, each a segment: `of('users', 7)`. */
57
- of(...owners: Key[]): BlobBucket;
58
- /** The object at a key, undefined when it holds none. */
59
- stat(key: string): Promise<BlobObject | undefined>;
60
- delete(key: string, options?: Pick<WriteOptions, 'ifMatch'>): Promise<void>;
61
- /** Writes to a key an object naming the source's bytes, which are neither read nor written. */
62
- copy(from: string, to: string, options?: WriteOptions): Promise<BlobObject>;
63
- /** Copy and the source's removal in one write. */
64
- move(from: string, to: string, options?: WriteOptions): Promise<BlobObject>;
65
- /** The objects under this folder and their bytes, counted from their rows. */
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
- objects: number;
68
- bytes: number;
109
+ count: number;
110
+ size: number;
69
111
  }>;
70
- /** Removes this folder's objects and every folder's under it, at once however many. */
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
- * Writes an object, returning once it is durable: whatever the key held is
84
- * replaced at the commit, whole, and an upload that does not commit leaves
85
- * nothing. A Blob, a file among them, gives its size and its type.
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
- put(key: string, body: Body, options?: PutOptions): Promise<BlobObject>;
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
- * Reads an object, undefined when the key holds none: what it is at once,
90
- * and its bytes as its body is read. A range, from offset and length bytes
91
- * long, is not checked against the object's hash.
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
- get(key: string, options?: {
94
- offset?: number;
95
- length?: number;
96
- signal?: AbortSignal;
97
- }): Promise<Download | undefined>;
178
+ slice(start?: number, end?: number): FileBytes;
98
179
  }