@tinyshed/tinystore 0.2.0 → 0.4.0

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
@@ -13,8 +13,8 @@ one. Every call, by engine, is in docs/reference/bun.md.
13
13
 
14
14
  <!-- /landing:headline -->
15
15
 
16
- > **Version 0.1, the first release.** Until `1.0`, a minor release may still
17
- > change the API, and its notes say what changed.
16
+ > **Version 0.3.** Until `1.0`, a minor release may still change the API,
17
+ > and its notes say what changed.
18
18
 
19
19
  The SDK starts a small `tinystore` server next to your program, called the
20
20
  sidecar, and talks to it over a local connection, so that several processes
package/dist/blobs.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { type Link } from './connection.ts';
2
+ import { type Home, type Open, type Via } from './handles.ts';
2
3
  import { type Stream } from './session.ts';
3
4
  import { type Duration } from './time.ts';
4
5
  /** A size in bytes: a number, or text in binary units, 64KiB or 2GiB; '2GB' does not compile. */
@@ -51,6 +52,18 @@ export interface FilePage {
51
52
  }
52
53
  /** Files as `store.files` opens them. */
53
54
  export declare function openFiles(link: Link, name: string, options?: FilesOptions): Files;
55
+ /** The open of a set of files, kept in the database of the handle `database` when it is given. */
56
+ export declare function filesOpen(name: string, options?: FilesOptions, database?: number): Uint8Array;
57
+ /** What a transaction needs of a set of files it takes in. */
58
+ export interface FilesParts {
59
+ readonly name: string;
60
+ readonly open: Open;
61
+ /** the database whose file keeps the files; the store's own when undefined */
62
+ readonly home: Home | undefined;
63
+ /** the same files, their calls through the transaction's `via` */
64
+ inside(via: Via): Files;
65
+ }
66
+ export declare function filesParts(handle: object): FilesParts | undefined;
54
67
  /**
55
68
  * A named set of files by path, or a folder of it, whose calls are the
56
69
  * folder's: a path in it is the folder's segments and then its own.
@@ -58,8 +71,12 @@ export declare function openFiles(link: Link, name: string, options?: FilesOptio
58
71
  export declare class Files {
59
72
  #private;
60
73
  readonly name: string;
61
- /** Files come from `store.files`. */
62
- constructor(link: Link, name: string, open: Uint8Array, folder: string[]);
74
+ /**
75
+ * Files come from `store.files` and `db.files`; inside a database's
76
+ * transaction, from `tx.with(files)`, whose writes go through the
77
+ * transaction.
78
+ */
79
+ constructor(link: Link, name: string, open: Open, folder: string[], home?: Home, via?: Via);
63
80
  /** The folder of these segments, one each: `folder('users', 42)` is users/42, never users/420. */
64
81
  folder(...segments: (string | number | bigint)[]): Files;
65
82
  /**
package/dist/blobs.js CHANGED
@@ -13,13 +13,22 @@ const decoder = new TextDecoder();
13
13
  const nothing = new Uint8Array(0);
14
14
  /** Files as `store.files` opens them. */
15
15
  export function openFiles(link, name, options) {
16
+ return new Files(link, name, filesOpen(name, options), []);
17
+ }
18
+ /** The open of a set of files, kept in the database of the handle `database` when it is given. */
19
+ export function filesOpen(name, options, database) {
16
20
  checkName(name, 'files');
17
- const open = BlobsOpen.encode({
21
+ return BlobsOpen.encode({
18
22
  name,
19
23
  ttl: options?.ttl === undefined ? undefined : ms(options.ttl),
20
24
  maxFileSize: options?.maxFileSize === undefined ? undefined : bytesOf(options.maxFileSize),
25
+ database,
21
26
  });
22
- return new Files(link, name, open, []);
27
+ }
28
+ // a set of files' parts, kept out of its public shape, for db.tx
29
+ const parts = new WeakMap();
30
+ export function filesParts(handle) {
31
+ return parts.get(handle);
23
32
  }
24
33
  /**
25
34
  * A named set of files by path, or a folder of it, whose calls are the
@@ -31,20 +40,35 @@ export class Files {
31
40
  #via;
32
41
  #open;
33
42
  #folder;
34
- /** Files come from `store.files`. */
35
- constructor(link, name, open, folder) {
43
+ #home;
44
+ /** whether its calls go through a database's transaction */
45
+ #inside;
46
+ /**
47
+ * Files come from `store.files` and `db.files`; inside a database's
48
+ * transaction, from `tx.with(files)`, whose writes go through the
49
+ * transaction.
50
+ */
51
+ constructor(link, name, open, folder, home, via) {
36
52
  this.name = name;
37
53
  this.#link = link;
38
- this.#via = viaLink(link);
54
+ this.#via = via ?? home?.via(`files ${name}`) ?? viaLink(link);
39
55
  this.#open = open;
40
56
  this.#folder = folder;
57
+ this.#home = home;
58
+ this.#inside = via !== undefined;
59
+ const inside = (through) => new Files(link, name, open, folder, home, through);
60
+ parts.set(this, { name, open, home, inside });
41
61
  }
42
62
  /** The folder of these segments, one each: `folder('users', 42)` is users/42, never users/420. */
43
63
  folder(...segments) {
44
- return new Files(this.#link, this.name, this.#open, [
45
- ...this.#folder,
46
- ...segments.map(segmentOf),
47
- ]);
64
+ const folder = [...this.#folder, ...segments.map(segmentOf)];
65
+ return new Files(this.#link, this.name, this.#open, folder, this.#home, this.#inside ? this.#via : undefined);
66
+ }
67
+ /** Refuses what streams a file's bytes inside a transaction, which takes a put's bytes whole. */
68
+ #outside(what) {
69
+ if (this.#inside) {
70
+ throw new InvalidError(`files ${this.name}: ${what} inside a transaction: put a file's bytes whole, and read them after its commit`);
71
+ }
48
72
  }
49
73
  /**
50
74
  * Writes the file whole and replaces whatever the path held, returning
@@ -146,6 +170,7 @@ export class Files {
146
170
  * leaving the block without commit aborts it.
147
171
  */
148
172
  async upload(path, options) {
173
+ this.#outside('an upload');
149
174
  const connection = await this.#link.connection();
150
175
  const write = BlobsWrite.encode({
151
176
  ...this.#fields(path, options),
@@ -236,6 +261,11 @@ export class Files {
236
261
  size: options?.size ?? source.size,
237
262
  create,
238
263
  };
264
+ if (this.#inside) {
265
+ const bytes = await allOf(source);
266
+ const answer = await this.#call('blobs.put', handle => BlobsWrite.encode({ ...fields, handle, bytes }), 'write');
267
+ return writtenOf(answer);
268
+ }
239
269
  return this.#link.run('write', async (connection) => {
240
270
  const handle = await this.#handle(connection);
241
271
  const piece = pieceOf(connection);
@@ -485,6 +515,25 @@ function sourceOf(body) {
485
515
  whole: async () => undefined,
486
516
  };
487
517
  }
518
+ /** Every byte of a body at once, as a put inside a transaction sends it. */
519
+ async function allOf(source) {
520
+ const chunks = [];
521
+ let size = 0;
522
+ for await (const chunk of source.chunks()) {
523
+ chunks.push(chunk);
524
+ size += chunk.length;
525
+ }
526
+ if (chunks.length === 1) {
527
+ return chunks[0];
528
+ }
529
+ const all = new Uint8Array(size);
530
+ let at = 0;
531
+ for (const chunk of chunks) {
532
+ all.set(chunk, at);
533
+ at += chunk.length;
534
+ }
535
+ return all;
536
+ }
488
537
  /**
489
538
  * The bytes of chunks again in pieces of `size` bytes, the last shorter. A
490
539
  * chunk that holds a whole piece goes as it is, without a copy.
@@ -76,6 +76,8 @@ export interface Started {
76
76
  durability?: Durability | undefined;
77
77
  /** the file of the store's encryption key, when it is not the store's own */
78
78
  encryptionKeyFile?: string | undefined;
79
+ /** the files of the store's older keys, which open what they sealed */
80
+ olderEncryptionKeys?: string[] | undefined;
79
81
  /** the node the store is, when it is one */
80
82
  node?: NodeOptions | undefined;
81
83
  /** measures the store into its own metrics, the machine too unless it says system: false */
@@ -192,7 +192,12 @@ function selfMetricsOf(given) {
192
192
  function storeFlags(started, dir) {
193
193
  const committing = started.durability === undefined ? [] : ['--durability', started.durability];
194
194
  const key = started.encryptionKeyFile;
195
- const keyed = key === undefined ? committing : [...committing, '--encryption-key-file', resolve(key)];
195
+ const sealing = key === undefined ? committing : [...committing, '--encryption-key-file', resolve(key)];
196
+ const older = (started.olderEncryptionKeys ?? []).flatMap(file => [
197
+ '--older-encryption-key',
198
+ resolve(file),
199
+ ]);
200
+ const keyed = [...sealing, ...older];
196
201
  const asked = selfMetricsOf(started.selfMetrics);
197
202
  const measured = asked === undefined
198
203
  ? keyed
@@ -552,6 +557,7 @@ export function embedded(runtime, dir, library, started = {}) {
552
557
  const options = StoreOptions.encode({
553
558
  durability: started.durability,
554
559
  encryptionKeyFile,
560
+ olderEncryptionKeys: (started.olderEncryptionKeys ?? []).map(file => resolve(file)),
555
561
  node: node !== undefined,
556
562
  from: node?.from ?? [],
557
563
  serve: node?.serve,
package/dist/index.d.ts CHANGED
@@ -13,7 +13,7 @@ export type { Bucket, BucketOptions, Counters, CountersOptions, Entry, Page as K
13
13
  export type { Allowance, Quota, Rate, RateLimit, RateLimitOptions, WindowUse } from './limits.ts';
14
14
  export type { HoldOptions, Lease, Lock, LockOptions, Permit, Semaphore, SemaphoreOptions, Tried, } from './locks.ts';
15
15
  export { type ConsoleOut, type Logger, type LoggerOptions, logger } from './logger.ts';
16
- export { type Aggregate, type AggregateQuery, type Bucket as MetricsBucket, type Buckets, type Condition as MetricsCondition, type Counter, type Damage as MetricsDamage, type Description as MetricsDescription, exponentialBuckets, type Gauge, type GaugeFuncOptions, type Histogram, type HistogramOptions, type InstrumentLabels, type InstrumentOptions, type LabelPage, type Labels, type LabelValue, type Metrics, type NameInfo, type NamePage, type Newest, type Op as MetricsOp, type PageOptions, type Percentile, type PercentileBucket, type Plan, type PrometheusOptions, type Query as MetricsQuery, type Series, type SeriesInput, type SeriesKind, type Timer, type TimerOptions, type Timing, type ValueBucket, type ValuePage, } from './metrics.ts';
16
+ export { type Aggregate, type AggregatePage, type AggregateQuery, type Bucket as MetricsBucket, type Buckets, type Condition as MetricsCondition, type Counter, type Damage as MetricsDamage, type Description as MetricsDescription, exponentialBuckets, type Gauge, type GaugeFuncOptions, type Histogram, type HistogramOptions, type InstrumentLabels, type InstrumentOptions, type LabelPage, type Labels, type LabelValue, type Metrics, type NameInfo, type NamePage, type Newest, type Op as MetricsOp, type PageOptions, type Percentile, type PercentileBucket, type Plan, type PrometheusOptions, type Query as MetricsQuery, type Series, type SeriesInput, type SeriesKind, type SeriesPage, type Timer, type TimerOptions, type Timing, type ValueBucket, type ValuePage, } from './metrics.ts';
17
17
  export type { Once, OnceOptions } from './once.ts';
18
18
  export type { ColumnType, Query, RowPage, Table, TableOptions, UpsertOptions } from './query.ts';
19
19
  export type { Aggregate as EventsAggregate, AllEvents, AppendOptions, Counted, Damage, Event, EventLevel, Events, EventsOptions, Fields, Level, Levels, Lines, NewEvent, Page as EventsPage, PollBatch, Query as EventsQuery, Row as EventsRow, Stats, StoreLoggerOptions, StreamInfo, TailBatch, TailQuery, Top, } from './records.ts';
package/dist/kv.d.ts CHANGED
@@ -118,6 +118,15 @@ export declare class Bucket<T> {
118
118
  expire(key: Key, when: Duration | Date, options?: Pick<WriteOptions, 'ifVersion'>): Promise<boolean>;
119
119
  /** Removes this branch's keys and every branch under it, at once however many. */
120
120
  clear(): Promise<void>;
121
+ /**
122
+ * Seals again with the store's sealing key every value of this branch, and
123
+ * of the branches under it, that an older key sealed, and says how many.
124
+ * Once every value of the bucket is, the older key can leave the store's
125
+ * options. A value sealed with a key the store does not hold stops it with
126
+ * an `InvalidError` that names the key, and a reseal after the key is given
127
+ * goes on.
128
+ */
129
+ reseal(): Promise<number>;
121
130
  /** One page of this branch's own keys, in the byte order of their text: `"10"` before `"9"`. */
122
131
  list(options?: {
123
132
  limit?: number | undefined;
package/dist/kv.js CHANGED
@@ -6,7 +6,7 @@ import { CorruptError, InvalidError } from './errors.js';
6
6
  import { checkName, handleOn, ownerText, viaLink, } from './handles.js';
7
7
  import { dateOf, ms, unixMs } from './time.js';
8
8
  import { textOf } from './wire/codec.js';
9
- import { KvBranch, KvBucketOpen, KvCall, KvCount, KvCountersOpen, KvEntry, KvFound, KvList, KvPage, KvWritten, methods, } from './wire/protocol.js';
9
+ import { KvBranch, KvBucketOpen, KvCall, KvCount, KvCountersOpen, KvEntry, KvFound, KvList, KvPage, KvResealed, KvWritten, methods, } from './wire/protocol.js';
10
10
  // a handle's parts, kept out of its public shape, for store.tx
11
11
  const parts = new WeakMap();
12
12
  export function partsOf(handle) {
@@ -98,6 +98,19 @@ export class Bucket {
98
98
  const under = underField(this.#under);
99
99
  await this.#via.call(methods['kv.bucket.open'], this.#open, methods['kv.clear'], handle => KvBranch.encode({ handle, under }), 'write');
100
100
  }
101
+ /**
102
+ * Seals again with the store's sealing key every value of this branch, and
103
+ * of the branches under it, that an older key sealed, and says how many.
104
+ * Once every value of the bucket is, the older key can leave the store's
105
+ * options. A value sealed with a key the store does not hold stops it with
106
+ * an `InvalidError` that names the key, and a reseal after the key is given
107
+ * goes on.
108
+ */
109
+ async reseal() {
110
+ const under = underField(this.#under);
111
+ const answer = await this.#via.call(methods['kv.bucket.open'], this.#open, methods['kv.reseal'], handle => KvBranch.encode({ handle, under }), 'write');
112
+ return KvResealed.decode(answer).count ?? 0;
113
+ }
101
114
  /** One page of this branch's own keys, in the byte order of their text: `"10"` before `"9"`. */
102
115
  async list(options) {
103
116
  const under = underField(this.#under);
package/dist/metrics.d.ts CHANGED
@@ -30,6 +30,10 @@ export interface Query {
30
30
  from?: Time | undefined;
31
31
  /** the range's end, excluded; now, a sample taken now in the range, unless given */
32
32
  to?: Time | undefined;
33
+ /** a page of read or aggregate: this many samples or buckets at most, 100,000 at most; without it, the whole answer or a limit error */
34
+ limit?: number | undefined;
35
+ /** the page after the one whose next this is, read with the same query and limit */
36
+ after?: string | undefined;
33
37
  }
34
38
  /** A series to write: its samples as [time, value] pairs, or as times and values columns. */
35
39
  export interface SeriesInput {
@@ -60,6 +64,18 @@ export interface Series {
60
64
  times: Float64Array;
61
65
  /** the values, whose bytes keep each one's bits: -0 and a NaN's payload survive */
62
66
  values: Float64Array;
67
+ /** a page cut the series here: the page its next reads begins with the rest of it */
68
+ more: boolean;
69
+ }
70
+ /**
71
+ * One page of a read: its series, and next while there is more. Walking it
72
+ * with for await gives its series, then those of each page after it, one
73
+ * page held at a time. Without limit it is the whole answer.
74
+ */
75
+ export interface SeriesPage extends AsyncIterable<Series> {
76
+ series: Series[];
77
+ /** where the page after it begins; absent on the last */
78
+ next?: string;
63
79
  }
64
80
  /** p and a rank: 'p95', 'p99.9'. The ranks offered are those asked most; any other is written the same way. */
65
81
  export type Percentile = 'p50' | 'p75' | 'p90' | 'p95' | 'p99' | 'p99.9' | (`p${number}` & Record<never, never>);
@@ -117,6 +133,17 @@ export interface Aggregate<O extends Op = Op> {
117
133
  labels: Labels;
118
134
  /** a bucket without samples is left out */
119
135
  buckets: Bucket<O>[];
136
+ /** a page cut the group here: the page its next reads begins with the rest of its buckets */
137
+ more: boolean;
138
+ }
139
+ /**
140
+ * One page of an aggregate: its groups, and next while there is more,
141
+ * walked as a SeriesPage is. A page ends between two whole buckets.
142
+ */
143
+ export interface AggregatePage<O extends Op = Op> extends AsyncIterable<Aggregate<O>> {
144
+ groups: Aggregate<O>[];
145
+ /** where the page after it begins; absent on the last */
146
+ next?: string;
120
147
  }
121
148
  /** A series' newest sample in the range. */
122
149
  export interface Newest {
@@ -200,15 +227,19 @@ export declare class Metrics {
200
227
  * await store.metrics.ingestPrometheus(text, { labels: { instance: 'web-1' } })
201
228
  */
202
229
  ingestPrometheus(text: string | Uint8Array, options?: PrometheusOptions): Promise<void>;
203
- /** The samples of each series the query finds, in its range: whole, or a limit error naming its bound. */
204
- read(query: Query): Promise<Series[]>;
230
+ /**
231
+ * The samples of each series the query finds, in its range: without limit
232
+ * the whole answer, or a limit error naming its bound; with limit a page,
233
+ * which may hold fewer samples than limit and still have next.
234
+ */
235
+ read(query: Query): Promise<SeriesPage>;
205
236
  /** The newest sample of each series the query finds, when it has one in the range. */
206
237
  latest(query: Query): Promise<Newest[]>;
207
238
  /**
208
239
  * The buckets of each group of the series the query finds, each one exact
209
240
  * value of op, rounded once; a bucket of count … last has its value.
210
241
  */
211
- aggregate<O extends Op>(query: AggregateQuery<O>): Promise<Aggregate<O>[]>;
242
+ aggregate<O extends Op>(query: AggregateQuery<O>): Promise<AggregatePage<O>>;
212
243
  /** What a read, or an aggregate when given its op, would spend of each bound; it decodes no sample. */
213
244
  explain(query: Query & Partial<Omit<AggregateQuery, keyof Query>>): Promise<Plan>;
214
245
  /** A page of the names the store holds samples of, in the byte order of their text. */
package/dist/metrics.js CHANGED
@@ -61,26 +61,41 @@ export class Metrics {
61
61
  await uploaded(stream, bytes, pieceOf(connection));
62
62
  });
63
63
  }
64
- /** The samples of each series the query finds, in its range: whole, or a limit error naming its bound. */
64
+ /**
65
+ * The samples of each series the query finds, in its range: without limit
66
+ * the whole answer, or a limit error naming its bound; with limit a page,
67
+ * which may hold fewer samples than limit and still have next.
68
+ */
65
69
  async read(query) {
66
- const parts = await this.#download('metrics.read', MetricsQuery.encode(queryOf(query)));
70
+ const parts = (await this.#download('metrics.read', MetricsQuery.encode(queryOf(query)))).map(part => MetricsRead.decode(part));
67
71
  const series = [];
68
72
  let more = false;
69
- for (const piece of parts.flatMap(part => MetricsRead.decode(part).series ?? [])) {
73
+ for (const piece of parts.flatMap(part => part.series ?? [])) {
70
74
  const times = timesOf(piece.times ?? new Uint8Array(0));
71
75
  const values = valuesOf(piece.values ?? new Uint8Array(0));
72
76
  const last = series.at(-1);
73
77
  if (more && last !== undefined) {
74
78
  last.times = joined(last.times, times);
75
79
  last.values = joined(last.values, values);
80
+ last.more = piece.more === true;
76
81
  }
77
82
  else {
78
83
  const kind = (piece.kind ?? 'gauge');
79
- series.push({ name: piece.name ?? '', kind, labels: piece.labels ?? {}, times, values });
84
+ const labels = piece.labels ?? {};
85
+ series.push({
86
+ name: piece.name ?? '',
87
+ kind,
88
+ labels,
89
+ times,
90
+ values,
91
+ more: piece.more === true,
92
+ });
80
93
  }
81
94
  more = piece.more === true;
82
95
  }
83
- return series;
96
+ const next = parts.at(-1)?.next;
97
+ const page = next === undefined ? { series } : { series, next };
98
+ return walked(page, at => at.series, after => this.read({ ...query, after }));
84
99
  }
85
100
  /** The newest sample of each series the query finds, when it has one in the range. */
86
101
  async latest(query) {
@@ -97,21 +112,30 @@ export class Metrics {
97
112
  * value of op, rounded once; a bucket of count … last has its value.
98
113
  */
99
114
  async aggregate(query) {
100
- const parts = await this.#download('metrics.aggregate', MetricsAggregateAsked.encode(aggregateOf(query)));
115
+ const asked = MetricsAggregateAsked.encode(aggregateOf(query));
116
+ const parts = (await this.#download('metrics.aggregate', asked)).map(part => MetricsAggregates.decode(part));
101
117
  const groups = [];
102
118
  let more = false;
103
- for (const piece of parts.flatMap(part => MetricsAggregates.decode(part).groups ?? [])) {
119
+ for (const piece of parts.flatMap(part => part.groups ?? [])) {
104
120
  const buckets = (piece.buckets ?? []).map(bucket => bucketOf(bucket));
105
121
  const last = groups.at(-1);
106
122
  if (more && last !== undefined) {
107
123
  last.buckets.push(...buckets);
124
+ last.more = piece.more === true;
108
125
  }
109
126
  else {
110
- groups.push({ name: piece.name ?? '', labels: piece.labels ?? {}, buckets });
127
+ groups.push({
128
+ name: piece.name ?? '',
129
+ labels: piece.labels ?? {},
130
+ buckets,
131
+ more: piece.more === true,
132
+ });
111
133
  }
112
134
  more = piece.more === true;
113
135
  }
114
- return groups;
136
+ const next = parts.at(-1)?.next;
137
+ const page = next === undefined ? { groups } : { groups, next };
138
+ return walked(page, at => at.groups, after => this.aggregate({ ...query, after }));
115
139
  }
116
140
  /** What a read, or an aggregate when given its op, would spend of each bound; it decodes no sample. */
117
141
  async explain(query) {
@@ -258,6 +282,23 @@ export class Metrics {
258
282
  return got.items.length === 0 ? [got.trailer] : [...got.items, got.trailer];
259
283
  }
260
284
  }
285
+ /**
286
+ * A page that for await walks: its items, then those of each page after it,
287
+ * the next page read only once the walk reaches the end of the one it holds.
288
+ */
289
+ function walked(page, items, readOn) {
290
+ return Object.assign(page, {
291
+ async *[Symbol.asyncIterator]() {
292
+ for (let at = page;;) {
293
+ yield* items(at);
294
+ if (at.next === undefined) {
295
+ return;
296
+ }
297
+ at = await readOn(at.next);
298
+ }
299
+ },
300
+ });
301
+ }
261
302
  /** A query as the wire carries it; a condition given as undefined is refused, never left out. */
262
303
  function queryOf(query) {
263
304
  const where = {};
@@ -273,6 +314,8 @@ function queryOf(query) {
273
314
  since: query.since === undefined ? undefined : ms(query.since),
274
315
  from: query.from === undefined ? undefined : unixMs(query.from),
275
316
  to: query.to === undefined ? undefined : unixMs(query.to),
317
+ limit: query.limit,
318
+ after: query.after,
276
319
  };
277
320
  }
278
321
  function conditionOf(label, condition) {
package/dist/sql.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { Files, type FilesOptions } from './blobs.ts';
1
2
  import { type Channel, type TxChannel } from './channels.ts';
2
3
  import type { Connection, Durability, Link } from './connection.ts';
3
4
  import { type Home, type Open, type Via } from './handles.ts';
@@ -171,6 +172,15 @@ export declare class Database implements Runner, Home {
171
172
  schema: S;
172
173
  }): Queue<StandardSchemaV1.InferOutput<S>>;
173
174
  queue<T = unknown>(name: string, options?: QueueOptions): Queue<T>;
175
+ /**
176
+ * A set of files kept in this database's file, as `store.files` keeps one
177
+ * in blobs.db: the same calls, and its writes commit with the rows in
178
+ * `db.tx`, through `tx.with(files)`. A file's bytes past 16 KiB lie in the
179
+ * folder beside the database's file.
180
+ *
181
+ * const packages = db.files('packages', { maxFileSize: '10MiB' })
182
+ */
183
+ files(name: string, options?: FilesOptions): Files;
174
184
  /**
175
185
  * An index of a table of this database, kept in its file: its rows found
176
186
  * again by their words, vectors or both, each hit's value its row as
@@ -266,6 +276,7 @@ export declare class SqlTx implements Runner {
266
276
  with<T>(bucket: Bucket<T>): Bucket<T>;
267
277
  with<T>(queue: Queue<T>): TxQueue<T>;
268
278
  with<T>(channel: Channel<T>): TxChannel<T>;
279
+ with(files: Files): Files;
269
280
  all<T = Row>(...statement: Statement): Promise<T[]>;
270
281
  one<T = Row>(...statement: Statement): Promise<T | undefined>;
271
282
  scalar<T = SqlValue>(...statement: Statement): Promise<T>;
package/dist/sql.js CHANGED
@@ -6,6 +6,7 @@
6
6
  import { AsyncLocalStorage } from 'node:async_hooks';
7
7
  import { readdir, readFile } from 'node:fs/promises';
8
8
  import { join } from 'node:path';
9
+ import { Files, filesOpen, filesParts } from './blobs.js';
9
10
  import { channelParts, txChannel } from './channels.js';
10
11
  import { checkDurability, download } from './connection.js';
11
12
  import { CancelledError, errorOf, InvalidError, OutcomeUnknownError } from './errors.js';
@@ -546,6 +547,19 @@ export class Database {
546
547
  queue(name, options = {}) {
547
548
  return openQueue(this.#link, this.#workers, name, options, this);
548
549
  }
550
+ /**
551
+ * A set of files kept in this database's file, as `store.files` keeps one
552
+ * in blobs.db: the same calls, and its writes commit with the rows in
553
+ * `db.tx`, through `tx.with(files)`. A file's bytes past 16 KiB lie in the
554
+ * folder beside the database's file.
555
+ *
556
+ * const packages = db.files('packages', { maxFileSize: '10MiB' })
557
+ */
558
+ files(name, options) {
559
+ const bytes = filesOpen(name, options);
560
+ const open = this.keep(methods['blobs.open'], bytes, async (connection) => filesOpen(name, options, await this.handle(connection)));
561
+ return new Files(this.#link, name, open, [], this);
562
+ }
549
563
  /**
550
564
  * An index of a table of this database, kept in its file: its rows found
551
565
  * again by their words, vectors or both, each hit's value its row as
@@ -787,7 +801,12 @@ export class SqlTx {
787
801
  this.#takes(queue.source.home, queue.source.open, `jobs queue ${queue.name}`);
788
802
  return queueVia(queue, this.#via);
789
803
  }
790
- throw new InvalidError(`${this.describe}: a transaction takes in a bucket or a queue opened from its database`);
804
+ const files = filesParts(handle);
805
+ if (files !== undefined) {
806
+ this.#takes(files.home, files.open, `files ${files.name}`);
807
+ return files.inside(this.#via);
808
+ }
809
+ throw new InvalidError(`${this.describe}: a transaction takes in a bucket, a queue or files opened from its database`);
791
810
  }
792
811
  async all(...statement) {
793
812
  return all(this, statementOf(statement));
package/dist/store.d.ts CHANGED
@@ -81,6 +81,14 @@ export interface OpenOptions {
81
81
  * running keeps the key it was started with.
82
82
  */
83
83
  encryptionKeyFile?: string;
84
+ /**
85
+ * The files of the store's older keys, which open the values they sealed
86
+ * and seal nothing new: a key being rotated out, until `reseal` has sealed
87
+ * every value again, or one found after a restore that left it out. Each
88
+ * file must be there. A sidecar found running keeps the keys it was
89
+ * started with.
90
+ */
91
+ olderEncryptionKeys?: string[];
84
92
  /**
85
93
  * Makes the store a node: it keeps a log of each file it writes, serves
86
94
  * its files to other nodes, and copies the files of the node it takes
package/dist/store.js CHANGED
@@ -317,6 +317,7 @@ export async function openWith(runtime, dir, options = {}) {
317
317
  const started = {
318
318
  durability,
319
319
  encryptionKeyFile: options.encryptionKeyFile,
320
+ olderEncryptionKeys: options.olderEncryptionKeys,
320
321
  node: options.node,
321
322
  selfMetrics: options.selfMetrics,
322
323
  maxSeries: options.maxSeries,